Manual (Non-Docker) Installation

How to install and run Atlantisboard without Docker, including systemd service configuration.

Manual (Non-Docker) Installation

This guide covers installing Atlantisboard directly on a server without Docker. Choose this path if your infrastructure restricts container usage or if you need fine-grained control over each service.

Recommendation: For most users, the Docker Compose installation is simpler and faster. Use this manual path only when Docker is not an option.

Prerequisites

Install and configure each of the following before proceeding:

Software Version Notes
Bun >= 1.3.5 Install Bun
MongoDB 8.x Must be configured as a replica set
Redis 7.x Used for session storage and rate limiting
MinIO Latest stable S3-compatible object storage
Git Any recent version To clone the repository

Step 1: Install Bun

curl -fsSL https://bun.sh/install | bash

Verify the installation:

bun --version

Ensure the version is 1.3.5 or later.

Step 2: Set Up MongoDB Replica Set

Atlantisboard requires MongoDB to run as a replica set for Change Streams (real-time collaboration). Even a single-node deployment needs replica set initialisation.

Install MongoDB 8.x

Follow the official MongoDB installation guide for your operating system.

Initialise the Replica Set

  1. Edit your MongoDB configuration (/etc/mongod.conf) to enable the replica set:
replication:
  replSetName: "rs0"
  1. Restart MongoDB:
sudo systemctl restart mongod
  1. Connect to the MongoDB shell and initialise the replica set:
mongosh

rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "localhost:27017" }
  ]
})
  1. Verify the replica set status:
rs.status()

You should see "stateStr": "PRIMARY" for your node.

Step 3: Install and Configure Redis

# Debian/Ubuntu
sudo apt install redis-server

# Verify
redis-cli ping
# Should return: PONG

For production, set a password in /etc/redis/redis.conf:

requirepass your-strong-redis-password

Then restart Redis:

sudo systemctl restart redis-server

Step 4: Install and Configure MinIO

Download and install the MinIO server:

wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/

Create a data directory and start MinIO:

sudo mkdir -p /var/lib/minio/data

MINIO_ROOT_USER=your-access-key \
MINIO_ROOT_PASSWORD=your-secret-key \
minio server /var/lib/minio/data --console-address ":9001"

Create the required buckets using the MinIO Client (mc):

# Install mc
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/

# Configure the alias
mc alias set local http://localhost:9000 your-access-key your-secret-key

# Create all 7 required buckets
mc mb local/import-inline
mc mb local/card-attachments
mc mb local/branding
mc mb local/fonts
mc mb local/user-avatars
mc mb local/backgrounds
mc mb local/backups

Tip: For production, run MinIO as a systemd service. See the MinIO documentation for service configuration examples.

Step 5: Clone and Build Atlantisboard

git clone https://github.com/your-org/atlantisboard.git
cd atlantisboard

Install dependencies:

bun install

Build the production bundle:

bun run build

This compiles the TypeScript server and bundles the React frontend into the dist/ directory.

Step 6: Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env and set all required variables. At a minimum:

NODE_ENV=production
PORT=3000

# MongoDB (use your replica set connection string)
MONGODB_URI=mongodb://localhost:27017/kanboard?replicaSet=rs0

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-strong-redis-password

# MinIO
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=your-access-key
MINIO_SECRET_KEY=your-secret-key

# Security secrets (generate each with: openssl rand -base64 48)
JWT_SECRET=<generated-secret-1>
SESSION_SECRET=<generated-secret-2>
CSRF_SECRET=<generated-secret-3>
ENCRYPTION_KEY=<generated-secret-4>

# Public URL
APP_URL=https://boards.example.com
CORS_ORIGIN=https://boards.example.com

See the Environment Variables Reference for the complete list.

Step 7: Start the Application

Main Server

bun run dist/server/index.js

The application will start on the configured PORT (default 3000).

The background worker handles scheduled tasks such as automatic backups and cleanup jobs. You can run it as a separate process:

bun run dist/server/workers/index.js

Alternatively, set ENABLE_CRON_JOBS_IN_MAIN=true in your .env to run scheduled jobs within the main server process (suitable for single-process deployments).

Step 8: Set Up systemd Services

For production, use systemd to manage Atlantisboard as a system service that starts automatically on boot.

Main Application Service

Create /etc/systemd/system/atlantisboard.service:

[Unit]
Description=Atlantisboard Application
After=network.target mongod.service redis-server.service
Wants=mongod.service redis-server.service

[Service]
Type=simple
User=atlantisboard
Group=atlantisboard
WorkingDirectory=/opt/atlantisboard
EnvironmentFile=/opt/atlantisboard/.env
ExecStart=/usr/local/bin/bun run dist/server/index.js
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/backups/atlantisboard

[Install]
WantedBy=multi-user.target

Background Worker Service (Optional)

Create /etc/systemd/system/atlantisboard-worker.service:

[Unit]
Description=Atlantisboard Background Worker
After=network.target mongod.service redis-server.service atlantisboard.service

[Service]
Type=simple
User=atlantisboard
Group=atlantisboard
WorkingDirectory=/opt/atlantisboard
EnvironmentFile=/opt/atlantisboard/.env
ExecStart=/usr/local/bin/bun run dist/server/workers/index.js
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true

[Install]
WantedBy=multi-user.target

Enable and Start the Services

# Create a dedicated system user
sudo useradd --system --create-home --shell /usr/sbin/nologin atlantisboard

# Set ownership
sudo chown -R atlantisboard:atlantisboard /opt/atlantisboard

# Reload systemd, enable, and start
sudo systemctl daemon-reload
sudo systemctl enable atlantisboard atlantisboard-worker
sudo systemctl start atlantisboard atlantisboard-worker

# Check status
sudo systemctl status atlantisboard

Verifying the Installation

  1. Check that the application is running:
curl -s http://localhost:3000/health

A successful response indicates the server is up and connected to MongoDB and Redis.

  1. Open http://<your-server-ip>:3000 in your browser. You should see the Atlantisboard login page.

  2. Proceed to Creating the First Admin Account.

Next Steps