Check the host.

uname -m && head -3 /etc/os-release && nproc && free -g && df -h /

Check: uname -m prints x86_64, and the size is at or above the floor. On an aarch64 host, stop: there is no image for it.

Install Docker Engine and the Compose plugin if docker compose version fails. Docker's convenience script runs as root and downloads packages, so read it before you run it.

curl -fsSL https://get.docker.com | sh

sudo systemctl enable --now docker

Add your user to the docker group (then log in again), or run every Docker command below with sudo.

sudo usermod -aG docker "$USER"

Check: docker compose version prints v2.x, and sudo docker run --rm hello-world succeeds.

Install the helper tools.

sudo apt-get update && sudo apt-get install -y curl jq openssl ca-certificates dnsutils

Check: command -v curl jq openssl dig prints four paths.

Open the firewall. Allow SSH first so you do not lock yourself out. If you use ufw:

sudo ufw allow OpenSSH && sudo ufw allow 80/tcp && sudo ufw allow 443/tcp && sudo ufw allow 443/udp && sudo ufw status

Careful: Docker publishes ports by writing firewall rules itself, so ufw does not protect a port that a container publishes. Only 80 and 443 should be reachable from outside. The database and Valkey are not published at all. With --domain (Step 4) the app's own port 3000 is bound to 127.0.0.1. Also open 80 and 443 in your hosting provider's own firewall or security group: ufw does not control it.

Check: sudo ss -ltnp 'sport = :80 or sport = :443' prints nothing. If another web server holds those ports, use your own reverse proxy instead of Caddy.

Recommended: add swap, so a memory spike slows the host down instead of ending in the out-of-memory killer, which may pick the database. Skip this if the host already has swap (swapon --show lists it).

sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

echo '/swapfile none swap sw,nofail 0 0' | sudo tee -a /etc/fstab

echo 'vm.swappiness=10' | sudo tee /etc/sysctl.d/20-swap.conf && sudo sysctl --system

A low swappiness (10 instead of the default 60) keeps PostgreSQL's cache in memory and uses swap only as an emergency buffer.

Check: swapon --show lists /swapfile, and sysctl vm.swappiness prints 10.

Find the server's public IPv4 address (run on the server).

curl -4fsS https://ifconfig.me

At your DNS provider, create an A record for app.example.com pointing at it (for example 203.0.113.10).

If a DNS proxy such as Cloudflare's orange cloud sits in front of the name, switch the record to DNS-only until the certificate is issued.

Fetch the pointer.

mkdir -p ~/juxtaboard && cd ~/juxtaboard

export RELEASE_URL="https://downloads.example.com"   # replace with the release address from the self-hosting page

curl -fsS "$RELEASE_URL/latest.json" -o latest.json && jq . latest.json

Check: valid JSON with version, url, sha256 and size, and free disk of at least three times size.

Download with resume, so a dropped SSH session does not restart the download, then verify the checksum.

curl -fL -C - --retry 5 -o release.tar "$(jq -r .url latest.json)"

echo "$(jq -r .sha256 latest.json)  release.tar" | sha256sum -c -

Check: release.tar: OK. Anything else: delete the file and download once more. The checksum proves the file arrived intact. It does not prove who published it, because it comes from the same place as the file.

Unpack.

VERSION=$(jq -r .version latest.json) && tar xf release.tar && cd "codedocs-$VERSION" && ls

Check: the listing shows image.tar.gz, docker-compose.yml, .env.example, install.sh and VERSION. Stay in this directory for the rest of the guide: every docker compose command runs here.

Open https://app.example.com. You land on the sign-in page.

Enter admin in Email and the generated password in Password, then press Sign in.

Open the profile button at the top right, choose User profile & settings, then Change password, and set your own password.

Leave ADMIN_INITIAL_PASSWORD in .env. Do not blank it. If the admin account is ever repaired at start, an empty value would reset it to a well-known default password.

Config, General, Public App URL: confirm it is https://app.example.com. Every emailed link is built from it.

Config, Email: choose SMTP or Resend, set the From address, press Test Connection, then Save.

Config, AI: add at least one AI provider and assign it the roles your projects use. Without one, AI features do nothing.

Config, Storage & Logs: keep Local filesystem, or switch to S3-compatible now, before users upload files.

Billing: once your own account appears in the list (it is created the first time it is needed, for example when you create a project), confirm it is on the Self-hosted plan (no plan limits, backups on). New accounts get that plan automatically through DEFAULT_PLAN_CODE=self_hosted; if an account is on another plan, change it here.

Install with plain HTTP, giving the final address.

./install.sh --url https://app.example.com --port 3000

Bind the app's port to the loopback interface, so only the proxy reaches it. In .env, set:

APP_BIND=127.0.0.1

docker compose up -d

The port is briefly open on all interfaces during the first install, so keep 3000 closed in your provider's firewall.

Create the nginx site. The map goes in the http context, for example in a file under /etc/nginx/conf.d/.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

    client_max_body_size 50M;
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
    server_tokens off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_buffering off;
    }
}

Why each part matters:

sudo nginx -t && sudo systemctl reload nginx

The Upgrade and Connection headers carry the WebSocket connections used for live editing. Without them, editors disconnect.

proxy_read_timeout and proxy_send_timeout of 86400 s keep long-lived WebSocket and event-stream connections open; the default 60 s cuts them.

proxy_buffering off lets event streams reach the browser as they happen.

client_max_body_size is the largest upload nginx accepts. 50 MB is the value in the project's reference configuration. The default Embed File Max Size (MB) setting is 100, so raise this to at least the size you want to allow.

X-Forwarded-Host and X-Forwarded-Proto tell the app which public address and scheme it is served on.

Get a certificate. Do this only after DNS points at the server.

sudo apt-get install -y certbot python3-certbot-nginx

sudo certbot --nginx --agree-tos --email you@example.com -d app.example.com

certbot adds the HTTPS listener and a redirect from port 80, and renews the certificate on its own timer.

PostgreSQL with the vector and pg_trgm extensions available. The app role must be allowed to run CREATE EXTENSION, or a superuser must create them first in the target database (CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS pg_trgm;). The first migration needs them, and the migration step stops with a clear message when it cannot enable them.

The bundled database runs PostgreSQL 17. Use 16 or newer; versions older than that are not checked.

A database owned by the app role, reachable over TCP with password authentication.

Valkey (or a Redis-compatible server) with persistence turned on. The bundle runs Valkey 8; other servers are not checked.

Back up. From the current release directory:

docker compose exec -T db pg_dump -U codedocs -Fc codedocs > ~/codedocs-$(date +%F).dump

cp .env ~/env-backup-$(date +%F)

Copy both files off the server. The full backup plan, including uploads and certificates, is in .

Download, verify and unpack the new release exactly as in Step 3, next to the old directory.

Copy the old .env into the new directory, then run the installer. Add --domain again if you use Caddy.

cp ../codedocs-OLD_VERSION/.env . && ./install.sh --domain app.example.com

Check: the output ends with running at ..., and curl -fsS http://127.0.0.1:3000/api/health shows "status":"ok" and the new build in its version block.

Remove release.tar and the old directory when you are satisfied. The data lives in Docker volumes, not in these directories.

Create the database, the role and the extensions. The extensions must exist before the migrations, because the first migration uses them and the app role cannot create the vector extension.

sudo -u postgres psql -v ON_ERROR_STOP=1 -c "CREATE ROLE juxtaboard LOGIN PASSWORD 'CHOOSE_A_LONG_PASSWORD'" -c "CREATE DATABASE juxtaboard OWNER juxtaboard"

sudo -u postgres psql -d juxtaboard -v ON_ERROR_STOP=1 -c "CREATE EXTENSION IF NOT EXISTS vector" -c "CREATE EXTENSION IF NOT EXISTS pg_trgm"

The app connects over TCP, so pg_hba.conf needs a host juxtaboard juxtaboard 127.0.0.1/32 scram-sha-256 line. Check: PGPASSWORD=... psql -h 127.0.0.1 -U juxtaboard -d juxtaboard -c '\dx' lists both extensions.

Write an environment file outside the checkout, mode 600, for example /etc/juxtaboard/app.env. The variables are described in the . The minimum is:

DATABASE_URL=postgresql://juxtaboard:CHOOSE_A_LONG_PASSWORD@127.0.0.1:5432/juxtaboard
VALKEY_URL=redis://127.0.0.1:6379
AUTH_SECRET=<output of: openssl rand -base64 48>
CONNECTOR_ENCRYPTION_KEY=<output of: openssl rand -base64 32>
PUBLIC_APP_URL=https://app.example.com
ADMIN_INITIAL_PASSWORD=<a long random password>
DEFAULT_PLAN_CODE=self_hosted
NODE_ENV=production
PORT=3000
HOSTNAME=127.0.0.1

The project declares its whiteboard package as file:../wboard/packages/whiteboard-core, so that package must sit next to the checkout and be built first. Then install, migrate and build. Valkey must be running during the build, because several route modules connect to it when Next.js collects page data.

(cd ../wboard && bun install && bun run build)

bun install && bun --env-file=/etc/juxtaboard/app.env run db:migrate && bun --env-file=/etc/juxtaboard/app.env run build

Check: db:migrate ends without an error, and the build ends with a route table.

Run the server under Node, not Bun. The stall detector (the watchdog) needs a native module that Bun cannot load; under Bun it switches itself off at every start and logs [Watchdog] Disabled. Set NEXT_MANUAL_SIG_HANDLE=true, so the app can save live documents and finish running jobs when it is told to stop. A minimal systemd unit:

[Unit]
Description=Juxtaboard
After=network-online.target postgresql.service valkey-server.service
Wants=network-online.target

[Service]
User=juxtaboard
WorkingDirectory=/srv/juxtaboard/app
EnvironmentFile=/etc/juxtaboard/app.env
Environment=NEXT_MANUAL_SIG_HANDLE=true
ExecStart=/usr/bin/node node_modules/next/dist/bin/next start
Restart=always
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target

Run it from the directory where you built, or from a copy that holds the build output (.next), node_modules, worker-dist, public, drizzle and package.json. Missing worker-dist makes every background job fail with MODULE_NOT_FOUND while the pages keep working. The stop timeout must exceed the app's 12-second shutdown budget.

Check: curl -fsS http://127.0.0.1:3000/api/health returns "status":"ok", and ls worker-dist lists the four *.worker.cjs files.

Put nginx and a certificate in front, as in Use your own reverse proxy. To update, repeat step 3 and restart the service.

: every environment variable and every System, Config setting.

, ,

: the list your project owners see.