Deployment

Bakend ships as a single compiled binary with an embedded admin dashboard. No Bun or Node.js runtime is required on the server.

For local development, see Getting Started. For install options, see Installation.

Release Binary

Download the archive for your platform from GitHub Releases:

bakend-v{version}-linux-x64.tar.gz
bakend-v{version}-linux-arm64.tar.gz
bakend-v{version}-darwin-arm64.tar.gz
bakend-v{version}-darwin-x64.tar.gz

Extract and verify the SHA256 checksum:

tar -xzf bakend-v1.0.1-linux-x64.tar.gz
sha256sum -c bakend-v1.0.1-linux-x64.tar.gz.sha256

Project Layout

/opt/bakend/
├── bak                 # compiled binary
├── bakend.json         # configuration
├── bakend.db           # SQLite database
├── storage/            # uploaded files
├── collections/        # collection definitions
├── functions/          # TypeScript functions
└── jobs/               # scheduled jobs

Scaffold with bak init (generates auth.jwtSecret) or copy bakend.json.example and set a strong secret.

Production checklist

  • Set BAKEND_ENV=production to warn on default JWT secrets
  • Set BAKEND_ADMIN_EMAIL before the first user registration
  • Terminate TLS at a reverse proxy (nginx, Caddy)
  • Set auth.jwtSecret to a random value (generated by bak init)
  • Run bak backup create before upgrades
  • Optional: logFile in bakend.json for persistent logs (BAKEND_LOG_FILE)

See RFC-0016 Security Model.

Start Manually

./bak start --config bakend.json

Verify:

curl http://localhost:8080/health
./bak version

systemd

  1. Create a dedicated user:
sudo useradd --system --home /opt/bakend --shell /usr/sbin/nologin bakend
  1. Install the binary and config:
sudo mkdir -p /opt/bakend
sudo cp bak /opt/bakend/
sudo cp bakend.json.example /opt/bakend/bakend.json
sudo chown -R bakend:bakend /opt/bakend
  1. Install the unit file from packaging/systemd/bakend.service:
sudo cp packaging/systemd/bakend.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bakend
  1. Check status:
sudo systemctl status bakend
curl http://localhost:8080/health

Docker

Build and run with Docker Compose:

export BAKEND_AUTH_JWT_SECRET=your-production-secret
mkdir -p data
cp bakend.json.example data/bakend.json
docker compose up -d

Or run the image directly:

docker run -d \
  -p 8080:8080 \
  -v "$(pwd)/data:/data" \
  -e BAKEND_AUTH_JWT_SECRET=your-production-secret \
  ghcr.io/alpbak/bakend:latest

Mount /data with bakend.json, collections/, functions/, jobs/, database, and storage.

Environment Overrides

VariableConfig key
BAKEND_PORTport
BAKEND_DATABASEdatabase
BAKEND_STORAGEstorage
BAKEND_LOG_LEVELlogLevel
BAKEND_AUTH_JWT_SECRETauth.jwtSecret
BAKEND_DASHBOARD_ENABLEDdashboard.enabled

Upgrade

  1. Stop the service: sudo systemctl stop bakend
  2. Backup database and storage:
bak backup create --output bakend-backup-$(date +%Y%m%d).tar.gz
  1. Download and replace the binary; verify SHA256
  2. Confirm version: /opt/bakend/bak version
  3. Start: sudo systemctl start bakend
  4. Verify: curl http://localhost:8080/health

Internal database schema migrations run automatically on startup. See RFC-0018.

Install Script

See Installation for full options. Quick examples:

# Latest release
sudo sh scripts/install.sh

# Specific version
sudo BAKEND_VERSION=1.0.1 sh scripts/install.sh

Optional systemd install (from repo checkout):

sudo BAKEND_INSTALL_SYSTEMD=1 sh scripts/install.sh