Install with Docker

This is the easiest way to run NovaDocs on a VPS. Docker starts:

a Postgres database
the NovaDocs app
applies the database schema
creates the admin account (seed)

1. Install Docker

On Ubuntu:

bash

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in so the docker group applies. Check:

bash

docker --version
docker compose version

2. Get the NovaDocs files

Download the NovaDocs package from BuiltByBit:

https://builtbybit.com/resources/novadocs.120459/

Upload the zip to your server (SFTP with WinSCP / FileZilla works well), then unzip it. Example:

bash

cd /var/www
unzip novadocs-*.zip -d novadocs
cd novadocs

Your folder name may differ depending on the zip you downloaded.

3. Create your environment file

.env

cp .env.example .env

Edit .env and set at least:

.env

AUTH_SECRET="paste-a-long-random-string-here"
NEXT_PUBLIC_APP_URL="http://YOUR_SERVER_IP:3000"
SEED_ADMIN_EMAIL="you@example.com"
SEED_ADMIN_PASSWORD="choose-a-strong-password"
SEED_ADMIN_NAME="Admin"

Tips:

AUTH_SECRET should be long and random (for example run openssl rand -hex 32)
After you point a domain + HTTPS at the app, change NEXT_PUBLIC_APP_URL to https://docs.yourdomain.com

Docker Compose already sets DATABASE_URL to the Postgres service. You usually do not need to change it for a basic Docker install.

4. Start NovaDocs

bash

docker compose up -d --build

First start can take a few minutes while the image builds.

Check that containers are running:

bash

docker compose ps
docker compose logs -f app

When you see that the app started, open:

http://YOUR_SERVER_IP:3000

Admin login: the email and password you set in .env.

Demo docs: /guide/docs/1.0/en/introduction

5. Useful Docker commands

bash

# Stop
docker compose down

# Start again
docker compose up -d

# View app logs
docker compose logs -f app

# Rebuild after an update (replace files with a new BuiltByBit download first)
docker compose up -d --build

# Re-run seed (updates guide docs / admin user)
docker compose exec app npm run db:seed

Domain + HTTPS (optional)

Put a reverse proxy in front of port 3000 (Caddy, Nginx, Traefik, or Cloudflare).

Example Caddyfile:

text

docs.yourdomain.com {
  reverse_proxy localhost:3000
}

Then set:

env

NEXT_PUBLIC_APP_URL="https://docs.yourdomain.com"

Restart:

bash

docker compose up -d

Troubleshooting

App keeps restarting
Run docker compose logs app and look for database errors. Wait until Postgres is healthy, then restart: docker compose restart app.

Cannot log in
Confirm SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD in .env, then:

bash

docker compose exec app npm run db:seed

Port 3000 already used
Change the ports line in docker-compose.yml from "3000:3000" to "8080:3000", then open port 8080 instead.