Docker Deployment

The recommended way to deploy pipel8ne is with Docker Compose. This brings up the full stack (MongoDB + backend + frontend) with a single command.

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• A server or VM with at least 512 MB RAM and 1 CPU core

Setup

1. Clone the repository

git clone https://github.com/ogb4n/pipel8ne.git
cd pipel8ne

2. Create the environment file

cp .env.example .env

Edit .env and set the required values:

JWT_SECRET=<generate: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))">
SECRETS_ENCRYPTION_KEY=<generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))">

See Environment Variables for the full list.

3. Build the frontend (first deploy only)

The frontend must be compiled before starting the stack:

cd webapp
npm install
npm run build
cd ..

The compiled output goes to webapp/dist/. The backend serves it as static files.

4. Start the stack

docker compose up -d

Check that all services are healthy:

docker compose ps

Expected output:

NAME                  STATUS
pipel8ne-backend      running
pipel8ne-mongo        running

The application is now available at http://localhost:3000.

5. Create the first admin account

Open the browser and register. The first account is automatically granted admin rights.

Then, go to Settings → Administration and disable public registration.

---

Updating

git pull
cd webapp && npm install && npm run build && cd ..
docker compose pull
docker compose up -d

---

Persisting data

By default, the MongoDB data is stored in a Docker named volume (pipel8ne_mongo_data). This volume persists across docker compose down restarts.

To check volumes:

docker volume ls | grep pipel8ne

To back up:

docker exec pipel8ne-mongo mongodump \
  --uri "mongodb://pipel8ne:<password>@localhost:27017/pipel8ne?authSource=admin" \
  --out /tmp/backup

docker cp pipel8ne-mongo:/tmp/backup ./backup-$(date +%Y%m%d)

---

Exposing to the internet

By default the app binds to 0.0.0.0:3000. To expose it securely with HTTPS, place it behind a reverse proxy (Nginx, Caddy, Traefik). See Production Checklist.

To change the port, set PORT=8080 in .env and update docker-compose.yml accordingly:

ports:
  - "8080:8080"

---

Stopping the stack

docker compose down          # keep data
docker compose down -v       # also delete volumes (⚠ destroys all data)