Just Dashboard Configuration reference
Environment variables and defaults for Just Dashboard.
The installer writes the settings needed for your chosen access path into a private .env in the repository. This page covers Just Dashboard 0.8.4. Administrators can change the address, certificate mode, network allowlist, ports, two-factor requirement, session policy, the web terminal, and update checks through Settings → Configuration; that page checks a restart and rolls back if the new stack does not come up. For other .env changes, run docker compose up -d to recreate affected containers; add --build when the code or images changed. A plain docker compose restart does not apply changed environment variables.
The dashboard controls the host. Keep it behind Tailscale, another private VPN with an explicit allowlist, or an SSH tunnel. Preserve the original .env and JD_MASTER_KEY when upgrading or reinstalling. If install.sh finds an earlier installation's data without its .env, it asks for the earlier key.
Required secret
| Variable | Value |
|---|---|
JD_MASTER_KEY | A fixed 64-character hex key. Generate one with openssl rand -hex 32. It seals stored TOTP seeds, database passwords, deployment secrets and credentials, notification channel credentials, backup credentials and the backup encryption key, the database certificate authority's key, and the SQL assistant's API key. Keep a separate copy for recovery; changing or losing it makes those stored secrets unreadable. |
Network and TLS
| Variable | Default | Purpose |
|---|---|---|
JD_SITE | localhost | Browser address and certificate name. A Tailscale install uses the machine's MagicDNS name. Keep it private; never set it to 0.0.0.0. |
JD_BIND | empty | Proxy listening address when it differs from JD_SITE. The Tailscale installer puts the tailnet IP here while JD_SITE remains the MagicDNS name. |
JD_TLS | internal | tailscale uses a certificate issued for the MagicDNS name; internal uses Caddy's private CA and prompts a browser warning; off is HTTP and is allowed only on loopback for an SSH tunnel. |
JD_ALLOWED_CIDRS | 127.0.0.1/32,::1/128 | Comma-separated networks permitted to reach the API, checked before authentication. For Tailscale, use 100.64.0.0/10,127.0.0.1/32,::1/128. Keep loopback for tunnel recovery. |
JD_TRUSTED_PROXIES | none in a standalone API; 127.0.0.1/32 in Compose | Proxies allowed to supply X-Forwarded-For. The bundled Caddy sets the client address. Do not trust arbitrary clients. |
JD_PORT | 8443 | Port you open in the browser. The installer chooses another if it is occupied. |
JD_BACKEND_PORT | 8080 before installer selection | API loopback port behind Caddy. The installer selects a free high port on a new installation. |
JD_FRONTEND_PORT | 3000 before installer selection | UI loopback port behind Caddy. The installer selects a free high port on a new installation. |
JD_ALLOWED_ORIGINS | empty | Full origins permitted to open WebSockets if UI and API use separate origins. Include scheme, host, and port. The normal single-origin stack does not need it. |
JD_ADDR | 127.0.0.1:8080 in a standalone API | Direct API bind. The bundled Compose file sets it to loopback using JD_BACKEND_PORT; setting JD_ADDR in .env alone does not replace that Compose value. |
The backend refuses a non-loopback JD_ADDR without an explicit JD_ALLOWED_CIDRS. Plain HTTP is only for loopback. For browser access instructions, see Reach your dashboard.
Authentication and behavior
| Variable | Default | Purpose |
|---|---|---|
JD_REQUIRE_2FA | false | If true, accounts without an authenticator must enroll before using the dashboard. An account already enrolled is asked for a code regardless of this setting. Shown as Require two-factor in Settings. |
JD_TERMINAL_ENABLED | true | Enables the web terminal, which opens a real shell on the host. Off removes the terminal's routes. Shown as Web terminal in Settings. |
JD_TERMINAL_USER | Lowest regular host account | Account used by terminal sessions. Empty chooses the lowest regular account. |
JD_TERMINAL_SHELL | Account's login shell | Shell for the web terminal. Empty honors the account's chsh setting. The installer normally sets the host's zsh. |
JD_REMOTE_DESKTOP_BRIDGE | empty | A Moonlight Web stream bridge on another tailnet machine, as host:port, used by Remote Desktop's Stream mode instead of the bridge container this server runs. Empty is the normal case. Such a bridge must listen on its tailnet address only and accept requests from this server alone. See Remote Desktop. |
JD_SESSION_TTL | 12h | Absolute sign-in lifetime. |
JD_SESSION_IDLE_TTL | 60m | Idle sign-in timeout. |
JD_DOCKER_HOST | unix:///var/run/docker.sock | Docker endpoint read by a standalone API. The bundled Compose stack fixes this to the local socket. |
JD_AGENT_MODE | false | Hub-managed agent mode with mutual TLS and no local login. It is not useful as a standalone panel. |
JD_DEV | false | Development-only HTTP cookie behavior. The bundled Compose file does not pass this setting from .env; do not use it on a real host. |
JD_LOG_LEVEL | info | Set debug for verbose backend logs. |
Deployments, databases, and monitoring
| Variable | Default | Purpose |
|---|---|---|
JD_DEPLOY_HEAVY_SLOTS | 1 | Concurrent deployment build or activation workers; range 1–8. |
JD_DEPLOY_LIGHT_SLOTS | 2 | Concurrent validation or metadata workers; range 1–8. |
JD_DEPLOY_LEASE_TTL | 30s | Time before a silent worker claim can be reconciled after a crash; range 5 seconds to 5 minutes. |
JD_DB_UPLOAD_MAX_MB | 2048 | Largest file one database import or one uploaded database dump may be, in MiB; range 1 to 1048576. Uploads are streamed, so this bounds disk use and time rather than memory. |
JD_METRICS_INTERVAL | 15s | Host and container sample interval. The runtime clamps it between 5 seconds and 5 minutes. |
JD_METRICS_RETENTION | 7d | How long the recorded metric history is kept. 0 disables recording while the live feed remains available. |
Files and host tools
These are comma-separated paths. A path must also be mounted into the backend container at the same host path for the bundled stack to see it.
| Variable | Default | Purpose |
|---|---|---|
JD_FILE_ROOTS | / | Paths the file manager may access. A readonly dashboard account can read files within these roots. |
JD_LOG_ROOTS | /var/log | Paths the log viewer may read. |
JD_COMPOSE_ROOTS | /opt,/srv,/home | Directories scanned for Compose stacks. |
JD_GIT_ROOTS | /opt,/srv,/home,/root | Directories scanned for Git repositories. |
JD_DEPLOY_ROOTS | /opt,/srv,/home,/root | Allowed local repository locations for deployment projects. A path outside them is refused. |
JD_NGINX_DIR | /etc/nginx | nginx configuration root for the Proxy page. |
JD_CADDYFILE | /etc/caddy/Caddyfile | Caddy configuration file for the Proxy page. |
JD_BACKUP_DIR | /var/backups/just-dashboard | Local backup destination and staging area. The bundled Compose stack mounts the default host directory; a different path also needs a matching mount. |
JD_DATA_DIR | /var/lib/just-dashboard | Dashboard state directory, including its SQLite database. Back it up. The bundled Compose stack fixes this path inside its container; editing .env alone does not move the volume. |
Updates and certificates
| Variable | Default | Purpose |
|---|---|---|
JD_UPDATE_CHECK | true | Check GitHub for a newer dashboard release. Turning it off leaves locally compiled release notes readable. Shown as Check for new versions in Settings. |
JD_UPDATE_REPO | JustDashboard/Just-Dashboard | Repository used for release discovery and in-app updates; change for a fork. |
JD_UPDATE_BRANCH | main | Branch followed for release discovery and in-app update pulls. 0.8.4 is released on main; change it to follow a fork or a branch of your own. |
JD_UPDATE_DIR | discovered | Checkout directory used by in-app updates. Leave empty unless Settings → Version says discovery failed. |
JD_ACME_DIRECTORY | Let's Encrypt | Optional ACME directory for deployment certificates. |
JD_ACME_CA_ROOT | system certificate roots | Absolute path to a PEM bundle for a private ACME authority. |
The 0.8.4 bundled Compose file does not forward JD_ACME_DIRECTORY or JD_ACME_CA_ROOT from .env into the backend container. They apply when the backend is launched with those variables directly, or when a custom Compose configuration passes them through.
Account linking
Both arrive in the release after 0.8.2. See Linked servers.
| Variable | Default | Purpose |
|---|---|---|
JD_ACCOUNT_LINK | true | Whether this server may be linked to a just-dashboard.com account at all. false removes the installer question, Settings → just-dashboard.com and the link command, and ends a link already in place. |
JD_ACCOUNT_URL | https://just-dashboard.com | The site a link goes to: an origin with no path. Plain http:// is accepted only for a loopback address, for development. |
First run only
| Variable | Default | Purpose |
|---|---|---|
JD_BOOTSTRAP_USER | admin | Username created only when the database has no users. |
JD_BOOTSTRAP_PASSWORD | empty | If empty, the backend generates a password, prints it once in its log, and requires a change at first sign-in. The guided installer sets a chosen or generated value here, so its password is not automatically forced to change. |
Durations require units such as 12h or 60m. Monitoring windows also accept days such as 7d. Boolean values use true or false. Invalid booleans, durations, numbers outside their range, allowlist entries, or a malformed JD_REMOTE_DESKTOP_BRIDGE stop startup with an error rather than silently using a default.