Deployment

Deploy a self-hosted Zoneless instance to a Linux server with Docker.

Choose a VPS provider

Zoneless runs on any Linux server with Docker. These steps use Ubuntu 24.04.

1Create a server

Image: Ubuntu 24.04 LTS
Plan: Shared CPU with at least 2GB RAM
Region: Pick the closest to your users
Authentication: Add an SSH key

Copy the server IP address after it finishes booting.

2SSH into your server

Connect using the SSH key added when you created the server.

Connect

ssh root@YOUR_IP_ADDRESS

3Install Docker

Install Docker using its official convenience script.

Install Docker

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

4Clone Zoneless

Clone the repository and navigate into it.

Clone

git clone https://github.com/zonelessdev/zoneless.git
cd zoneless

5Configure environment

Copy the production example and set your public dashboard URL, app secret, network, and tenancy mode. The example below uses mainnet. Set LIVEMODE=false for test mode (simulated funds by default). To test real Devnet transactions instead, also set SETTLEMENT_RAIL=onchain. See Environment variables for optional settings.

Copy the example file

cp .env.production.example .env.production
nano .env.production

.env.production

DASHBOARD_URL=http://YOUR_IP_ADDRESS
APP_SECRET=your_generated_secret_here
LIVEMODE=true
SINGLE_TENANT=true

6Start Zoneless

Build and start the containers. The first build may take a few minutes.

Start

docker compose --env-file .env.production up -d --build

7Check the deployment

Check the API using the server IP, then open http://YOUR_IP_ADDRESS/setup and complete the setup wizard.

Verify

curl http://YOUR_IP_ADDRESS/api/health

Next steps

Backups: Back up MongoDB and test restoring it before you need it.
Monitoring: Check /api/health, disk space, and container logs.
Updates: Review release notes, pull the new version, and rebuild the containers.