Skip to main content
Deploy

AWS / GCP / Azure

RushDB runs well on a single Linux VM with Docker Compose. The lowest-friction path is to boot an Ubuntu VM with the cloud-init template below, after replacing the placeholder external Neo4j/Aura values in the user-data file.

Verify the Prerequisites first.

View cloud-initDocker Compose template
SettingMinimumRecommended
OSUbuntu 22.04 LTSUbuntu 22.04 or 24.04 LTS
CPU2 vCPU4 vCPU
RAM4 GB8 GB
Disk30 GB SSD50+ GB SSD with snapshots
Public ports22, temporary 3000, 80, 443Close 3000 after TLS proxy is configured

Do not expose Neo4j (7474, 7687) or Postgres (5432) publicly.

Fast Path: Cloud-Init​

Download the template locally:

curl -L -o rushdb-cloud-init.yaml https://raw.githubusercontent.com/rush-db/rushdb/main/deploy/templates/cloud-vm/cloud-init.yaml

The template installs Docker, downloads the RushDB Compose stack to /opt/rushdb/compose.yaml, writes /opt/rushdb/.env, opens SSH and port 3000, and starts RushDB. Before production use, replace every placeholder in the cloud-init file or in /opt/rushdb/.env.

After first boot, SSH into the VM and rotate the generated configuration:

cd /opt/rushdb
sudo nano .env

# Required changes before production:
# RUSHDB_PASSWORD
# RUSHDB_AES_256_ENCRYPTION_KEY="$(openssl rand -hex 16)"
# NEO4J_URL
# NEO4J_USERNAME
# NEO4J_PASSWORD
# POSTGRES_PASSWORD
# RUSHDB_DASHBOARD_URL=https://rushdb.example.com
# RUSHDB_BASE_URL=https://rushdb.example.com

sudo docker compose --env-file .env -f compose.yaml up -d

Use the AWS console or CLI to launch an Ubuntu EC2 instance with user data from rushdb-cloud-init.yaml.

Recommended defaults:

  • Instance type: t3.medium or larger
  • Storage: 50 GB gp3
  • Security group:
    • 22/tcp from your IP
    • 3000/tcp from your IP for first verification
    • 80/tcp and 443/tcp from 0.0.0.0/0 when using a reverse proxy

CLI shape:

aws ec2 run-instances \
  --image-id ami-REPLACE_WITH_UBUNTU_AMI \
  --instance-type t3.medium \
  --key-name YOUR_KEY_PAIR \
  --security-group-ids sg-REPLACE \
  --subnet-id subnet-REPLACE \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":50,"VolumeType":"gp3","DeleteOnTermination":true}}]' \
  --user-data file://rushdb-cloud-init.yaml

Ubuntu AMI IDs are region-specific; select the current Ubuntu LTS AMI in the EC2 launch wizard or through your standard image catalog.

Manual Path​

After SSHing into your VM, install Docker and start the same Compose stack manually:

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

mkdir rushdb && cd rushdb
curl -L -o compose.yaml https://raw.githubusercontent.com/rush-db/rushdb/main/deploy/templates/docker-compose/compose.yaml
curl -L -o .env https://raw.githubusercontent.com/rush-db/rushdb/main/deploy/templates/docker-compose/.env.example

nano .env
docker compose up -d

Required .env edits:

VariableWhat to set
RUSHDB_PASSWORDStrong dashboard admin password
RUSHDB_AES_256_ENCRYPTION_KEYExactly 32 characters; generate with openssl rand -hex 16
RUSHDB_DASHBOARD_URLPublic URL, e.g. https://rushdb.example.com
RUSHDB_BASE_URLSame public API URL
NEO4J_URLExternal Neo4j/Aura Bolt URL
NEO4J_USERNAMEExternal Neo4j/Aura username
NEO4J_PASSWORDExternal Neo4j/Aura password
POSTGRES_PASSWORDStrong internal Postgres password

See Environment Variables for the full reference.

TLS with Caddy​

Once DNS points at the VM, put RushDB behind HTTPS:

sudo apt install -y caddy
sudo tee /etc/caddy/Caddyfile >/dev/null <<'EOF'
rushdb.example.com {
  reverse_proxy 127.0.0.1:3000
}
EOF
sudo systemctl reload caddy

Then update /opt/rushdb/.env or your deployment directory:

RUSHDB_DASHBOARD_URL=https://rushdb.example.com
RUSHDB_BASE_URL=https://rushdb.example.com

Restart RushDB and remove public access to port 3000 from your cloud firewall or security group.

Backups and Persistence​

The Docker Compose template stores Neo4j and Postgres data in Docker volumes. For production:

  • Enable VM disk snapshots or provider backups.
  • Prefer a separate attached disk for Docker data if your operations policy requires it.
  • Test restore from a snapshot before relying on it.
  • Keep Neo4j and Postgres ports private.

Verify​

curl http://VM_PUBLIC_IP:3000/health
# or, after TLS:
curl https://rushdb.example.com/health

Then open the dashboard, sign in with RUSHDB_LOGIN / RUSHDB_PASSWORD, and continue with Get your API Key.

Troubleshooting​

cd /opt/rushdb # or your manual deployment directory
docker compose --env-file .env -f compose.yaml ps
docker compose --env-file .env -f compose.yaml logs -f rushdb
docker compose --env-file .env -f compose.yaml logs -f neo4j

Common failures:

SymptomCheck
Container exits immediatelyRUSHDB_AES_256_ENCRYPTION_KEY must be exactly 32 characters
Browser cannot connectCloud firewall/security group and VM firewall both need the port open
RushDB cannot reach Neo4jNeo4j health, NEO4J_PASSWORD, and APOC plugin startup
API works on 3000 but HTTPS failsDNS record, Caddy logs, and ports 80 / 443