Self-hosted install

Updated October 2026

Describes how to run the Dousen server (DousenCore) on your own infrastructure with Docker Compose, including configuration, licensing, directory sign-in, and troubleshooting.

One container runs the API and web portal, and one runs MariaDB. DousenDesktop and the Unreal plugin talk to the API over HTTP and JSON on port 8080. Dousen’s cloud control plane, DousenControl, issues your signed license and receives your instance’s license heartbeat. You don’t run it yourself.

The deployment bundle in deploy/self-hosted/ contains docker-compose.yml, the install.sh helper, an annotated .env.example, and SELF_HOSTING.md with operational notes. Where those files differ from this page, follow this page. If you don’t have the bundle, email [email protected].

Requirements

• A Linux host (Ubuntu 22.04+ or Debian 12+) with Docker 24+, Docker Compose v2, and at least 2 GB RAM (4 GB recommended).
• Persistent storage, and an HTTPS hostname for the studio.
• A Dousen license: the token and its public key, issued for your studio. Self-serve issuance isn’t live yet, so email [email protected] to get one. Without a license, DousenCore starts locked (see Licensing).
• Optionally, a Perforce server, a Jira Cloud site, an LDAP or Active Directory directory, and an SMTP server for invite and password-reset emails.

Install and verify a studio server

1. Run the install script or follow the Install steps. Keep the .env file private, because it holds the database credentials and secrets.
2. Start the Compose services and read the logs. The database should initialize, with no JWT secret error and no Core is locked license message.
3. Create the first admin, open /portal/ at the studio’s HTTPS hostname, and sign in. Create one test project, then invite one test artist.
4. On an artist workstation, sign in to DousenDesktop against that hostname. Set up the artist’s own Jira and Perforce access in Desktop, which is separate from the server-side integrations.
5. Install the matching DousenUE plugin, configure the test project, and run a complete test publish.
6. Before rollout, back up the database, the persistent data, and the deployment configuration. Restore the backup to a test instance, then sign in to the portal and DousenDesktop on it as in steps 3 and 4.

The server is ready when portal sign-in, project configuration, artist sign-in, and a saved Unreal import all work through the studio URL. A healthy container doesn’t prove this, because /health keeps answering while Core is locked.

Install

Run every docker compose command on this page from the directory that holds docker-compose.yml and .env (~/.dousen if you used install.sh).

1. Copy the bundle and create your env file.

   Copy deploy/self-hosted/ to the host and copy .env.example to .env. Every setting on this page goes in this file. If you ran install.sh, it already wrote ~/.dousen/.env, so skip this step.

2. Fill in the required values.

   Set the database passwords, DOUSEN_JWT_SECRET, and your license key and public key. Put the public key in double quotes, either on several lines or on one line with \n between the lines. Replace the placeholder secrets with generated ones:

   SHELLopenssl rand -hex 32

   DOUSEN_JWT_SECRET must be at least 32 bytes. If it’s shorter, DousenCore exits at startup with JWT secret must be at least 32 bytes, got N. Length is the only check, so the 33-character placeholder in .env.example passes. Replace it with the 64-character output of openssl rand -hex 32.

3. Start the stack.

   SHELLdocker compose up -d

   The API container waits until MariaDB reports healthy, runs its database migrations, and starts on port 8080. Migrations run on every start, so there’s no separate migration step.

4. Check that the server answers.

   SHELLcurl http://localhost:8080/health

   The admin portal is at http://<server>:8080/portal/, and / and /portal both redirect there. Next, create the first admin.

Create the first admin

A new instance has no users, and the portal has no sign-up page, so create the first admin with dousen-cli, which is in the container image. Set your license first, because a locked instance refuses portal sign-in.

SHELLdocker compose exec dousen-api sh -c 'dousen-cli --database-url "$DOUSEN_DATABASE_URL" \
  create-user --email [email protected] --display-name "Studio Admin" --role admin \
  --password "choose-a-strong-password"'

The command creates the account under a placeholder tenant. DousenCore moves it to your licensed tenant when it starts, so restart the API container afterward:

SHELLdocker compose restart dousen-api

Open /portal/ and sign in with that email and password. Because the password was typed on the command line, change it on your account page (/portal/account). From then on, add people with Invite User (see User and auth management).

With directory sign-in (DOUSEN_AUTH_MODE=ldap), you can skip the command. The first successful sign-in by a member of DOUSEN_LDAP_ADMIN_GROUP creates an Admin account, provided that Dousen has a user search base (see Directory sign-in).

Configuration reference

All server settings are environment variables in .env. The shipped docker-compose.yml passes only the variables listed in the environment: block of the dousen-api service, so any other variable in .env has no effect. The tables below mark the settings that block lacks. To use one, add it in the same form as the existing entries (VAR: ${VAR:-default}).

Required

Optional

Email: invites and password resets (SMTP)

DousenCore uses SMTP to email invites (Invite User) and password-reset links. The default compose file doesn’t pass these variables through, so add them to the environment: block.

With DOUSEN_SMTP_HOST unset, Invite User still creates the account and Send reset link still creates the reset token, but no email goes out. The portal then shows "… was created, but SMTP isn't configured on this instance — no email was sent." after an invite and "SMTP not configured — no email sent. The link is logged only at debug level (RUST_LOG=info,dousen_api::email=debug)" after a reset. The invite message also says the link is logged only at debug level. A malformed DOUSEN_SMTP_HOST logs a warning at startup and behaves the same way.

Core logs the link only at the debug level. To get it:

1. Set RUST_LOG=info,dousen_api::email=debug in .env and run docker compose up -d.
2. Click Resend invite in the user’s row, or Send reset link for an account that already has a password. Then search the log for the email (SMTP disabled) line:

   SHELLdocker compose logs dousen-api | grep "email (SMTP disabled)"

3. Give the link to the user yourself.
4. Set RUST_LOG back to info, because that log line contains the token.

Once SMTP is configured, the same actions send the email over STARTTLS, and the portal reports "Invitation sent to …" or "Reset link sent".

Directory sign-in (LDAP / Active Directory)

By default, users sign in with passwords stored on the instance (DOUSEN_AUTH_MODE=local). To use your directory instead, set DOUSEN_AUTH_MODE=ldap. DousenCore then creates an account on a user’s first successful sign-in: members of the admin group become Admins and everyone else becomes an Artist. After that, the role you set in Dousen wins (see Which role wins).

Dousen binds as the signing-in user, so you don’t need a service account, and it always rejects empty passwords. If the directory returns no mail attribute for a user, the login name becomes the Dousen account identifier.

Connect DousenDesktop and Unreal

Check that /health answers before you give DousenDesktop to artists. Then, on each workstation:

1. Install DousenDesktop and choose Self-hosted on first launch.

   Onboarding asks whether the studio is Dousen Cloud or Self-hosted. Choose Self-hosted and enter the Server URL: the address your reverse proxy exposes, or, on a trusted LAN, the host’s address on port 8080. Click Test Connection and continue after it shows ✓ Connected. The test only checks /health, which also answers while Core is locked, and setup doesn’t require it to pass. Then finish setup.

2. Sign in.

   With DOUSEN_AUTH_MODE=local, artists sign in with the email and password they set from their invite email (see User and auth management). With DOUSEN_AUTH_MODE=ldap, they sign in with their directory credentials.

To change the address later, edit the server URL on the Connection tab of DousenDesktop’s Settings dialog.

The Unreal plugin has its own server settings in Config/DefaultDousenUE.ini. Set ServerScheme and ServerHost to the same server as the Server URL in Desktop. The plugin takes its DousenCore access token from Desktop’s credential file (core.credentials.json, next to bridge.token), and uses it only when the server URL in that file matches. Artists open Unreal themselves while DousenDesktop is running and signed in. For ProjectId, the bridge port, and environment overrides, see Configure the plugin.

Licensing

The license is an Ed25519-signed JWT (DOUSEN_LICENSE_KEY) plus the public key issued with it (DOUSEN_LICENSE_PUBLIC_KEY_PEM). The token encodes your tier, seat count, features, and expiry. DousenCore verifies it offline against the public key, so it works on an air-gapped network.

DousenCore fails closed. Without a valid license it starts locked, and the only bypass is the development setting below. At startup:

A locked instance keeps running, but the portal, the /api/* endpoints, and the Jira webhook return HTTP 403 with "code": "unlicensed" and a message that starts with Dousen Core is unlicensed:. Artists can’t sign in or refresh their sessions. /health and /metrics still answer.

The instance can also lock while it’s running:

• Expiry: Core checks the expiry locally every hour. When the license passes the end of its grace period, Core locks and logs license expiry recheck failed: … — Core is now locked.
• Heartbeat: unless DOUSEN_CONTROL_PLANE_URL is empty, Core sends the control plane a heartbeat with its user count at startup and then every 24 hours. If the control plane replies with a JSON 403 whose code is revoked, cancelled, or suspended, Core locks and logs license <code> by control plane: … — Core is now locked. Any other 403, such as a block page from a proxy or firewall, is logged as a warning and doesn’t lock the instance. Other error responses and network failures are only logged, and Core retries on the next heartbeat.

While locked, Core sends a heartbeat every hour. If you fix the cause on the control-plane side, for example by paying or getting the license unsuspended, the instance can unlock within the hour. After a revoked or cancelled reply, Core remembers the rejection across restarts, so only a newly issued license unlocks it. A heartbeat can also deliver a renewed license, which Core saves and uses on later starts.

To turn the heartbeat off, set DOUSEN_CONTROL_PLANE_URL= to an empty value in .env. With the heartbeat off, a revoked license keeps working until the license token expires and the 14-day grace period ends.

For local development only, DOUSEN_DEV_UNLICENSED=true turns on every feature with unlimited seats and no license. Core logs DOUSEN_DEV_UNLICENSED=true — running with an all-features, unlimited-seat license at startup. Not in the default compose file. Never set it in a production configuration.

To renew, replace DOUSEN_LICENSE_KEY in .env with the renewed token and run docker compose up -d.

Operational notes

• Backups: the database is in the dousen-mariadb Docker volume. docker volume ls lists it as <project>_dousen-mariadb, where the project name defaults to the name of the install directory. Include the volume in your backup routine. A logical dump looks like this:

  SHELLdocker exec dousen-mariadb sh -c \
    'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" dousen' \
    > dousen-backup-$(date +%Y%m%d).sql

  The single quotes make the container’s shell expand MARIADB_ROOT_PASSWORD, which exists only inside the container. Back up .env too, because it holds your license key and secrets, and store it outside the Docker volume.
• Upgrades: change DOUSEN_VERSION, then run docker compose pull && docker compose up -d. Migrations run on start. If you later roll back to a version older than migration 0032, deactivated accounts can sign in again.
• Perforce in Docker: the compose file includes a commented-out p4d service for a self-contained evaluation stack.
• Kubernetes: Docker Compose is the supported path for self-hosted studios. The Helm chart in infra/helm/dousencore/ uses the same environment variables but is built for the managed GKE deployment that DousenControl provisions (Cloud SQL, Workload Identity, and a cert-manager ingress). To use it on another cluster, set mariadb.enabled: true and replace the ingress and Cloud SQL values instead of running helm install unmodified.

Troubleshooting