Humlens Beta
Menu
Humlens Localization · setup guide

Set up Humlens Localization

Run Localization on your own servers with one Docker Compose file: the app with video processing built in, Postgres, Redis and your own storage, using your own AI provider keys.

Time
About 20 minutes with Docker Compose
Local ports
App 4002
Who does what
A developer installs; your team does the first-run setup in the app.

Before you start

Docker and Docker Compose

On any Linux server or cloud VM

A domain and reverse proxy

nginx, Caddy or Traefik in front for HTTPS; the container serves plain HTTP

OpenAI API key

Required: powers translation, transcription and dubbing. Anthropic and Mistral are optional extras for text.

SMTP

For invitations, magic links and password resets

Storage

An S3-compatible bucket, or the bundled MinIO

For your developer

Install

  1. 1

    Create the settings file

    At minimum set NEXTAUTH_SECRET, APP_URL and NEXTAUTH_URL, POSTGRES_PASSWORD, OPENAI_API_KEY and the SMTP settings.

    cd humlens/apps/humlens-localization
cp .env.selfhost.example .env
  2. 2

    Start everything

    This starts the app on port 4002, applies database migrations once, and runs Postgres 16 and Redis 7.

    docker compose -f docker-compose.selfhost.yml up -d
  3. 3

    No S3 bucket? Add MinIO

    MinIO is defined but only starts with its profile. Set MINIO_ROOT_USER and MINIO_ROOT_PASSWORD first.

    docker compose -f docker-compose.selfhost.yml --profile minio up -d
  4. 4

    Put HTTPS in front

    Point your reverse proxy at the app port (APP_PORT, default 4002) and terminate TLS there.

For your developer

Settings

These go in the .env file, or your host's secret manager in production.

Setting Needed What it is
APP_URL, NEXTAUTH_URL Required The app's public address
NEXTAUTH_SECRET Required Random string; also secures the app's internal video-processing calls
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB Required Change the example password before production
OPENAI_API_KEY Required Your own key: translation, transcription and dubbing
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM Required Outbound email
ANTHROPIC_API_KEY, MISTRAL_API_KEY Optional Extra providers for text workflows
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION Optional Your S3-compatible bucket; or use MinIO
GITHUB_CLIENT_*, GOOGLE_CLIENT_*, AUTH_PROVIDERS Optional Social sign-in
DEPLOYMENT_MODE, LICENSE_KEY, FEATURE_TEAM_* Optional Enterprise features (SSO, directory sync, audit log) need a license, the matching flag, and their service (BoxyHQ Jackson or Retraced).

For your team

First-run setup

Done in the app's own screens, in this order. No code involved.

  1. 01

    Create your account and team

    Open your address, sign up and create the team. The creator is its Owner.

  2. 02

    Invite your team

    Invite translators, reviewers and admins by email; invitations use your SMTP settings.

  3. 03

    Create your first project

    Add the languages you're localizing into, then bring in your strings, documents or media.

  4. 04

    Set your quality rules

    Add glossary terms and tone rules so AI drafts and review agents follow your brand.

Check it works

  • The app loads over HTTPS at your address and you can sign up.
  • Invitation and sign-in emails arrive.
  • A short text translates, and a short video transcribes, which confirms the OpenAI key.
  • Uploaded media appears in your bucket (or MinIO).

Troubleshooting

Translations or video jobs fail

Check OPENAI_API_KEY and that the account has credit.

Emails don't arrive

Check the SMTP_* settings and your provider's sending limits.

SSO, directory sync or audit log don't appear

They need DEPLOYMENT_MODE=selfhost, a license, the FEATURE_TEAM_* flag, and their service running.

Browsers warn the site isn't secure

Put a reverse proxy with TLS in front; the container itself serves plain HTTP.

Going live

  • Fresh NEXTAUTH_SECRET per deployment; example passwords changed.
  • Back up Postgres daily: docker compose -f docker-compose.selfhost.yml exec db pg_dump …
  • Back up your storage bucket separately.
  • Upgrade by pulling, rebuilding app and migrate, backing up, then starting migrate before app.
  • Keep SECURITY_HEADERS_ENABLED=true and the app behind TLS.

Rather have us set it up?

Our team can install Localization in your AWS, GCP or Azure account and configure it with you.

Talk to us Back to Localization