Host Map Blueprint on a cloud server

Put your instance on an always-on server so remote teammates can reach it from anywhere — with your own domain and free HTTPS. This guide uses Oracle Cloud's Always-Free tier, which can run Map Blueprint at no monthly cost, but the steps apply to any Ubuntu cloud server.

Prefer to just run it on your own laptop? See the local hosting guide.

Step 1 — Create a free server

1. Sign up at Oracle Cloud Free Tier and log in to the console.
2. Go to Compute → Instances → Create instance.
3. Choose an Always-Free-eligible shape. Either is fine: VM.Standard.E2.1.Micro (x86) or an Ampere Arm shape (more memory). Keep the default Ubuntu image.
4. Under Add SSH keys, choose Generate a key pair for me and download the private key — you'll need it to log in. (Or paste your own public key if you already have one.)
5. Click Create. When it's running, copy its Public IP address — this guide calls it YOUR_SERVER_IP.

Step 2 — Open the firewall

Oracle blocks inbound traffic by default. Allow web traffic so people can reach the app:

1. Open your instance → click its Virtual Cloud Network / subnet → Security Lists → the default list.
2. Add Ingress Rules allowing TCP from 0.0.0.0/0 to ports 80 and 443 (HTTP and HTTPS).

sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 80 -j ACCEPT
sudo iptables -I INPUT 6 -m state --state NEW -p tcp --dport 443 -j ACCEPT
sudo netfilter-persistent save

Step 3 — Connect to the server

From your own computer, open a terminal and SSH in using the private key you downloaded:

ssh -i /path/to/YOUR_PRIVATE_KEY ubuntu@YOUR_SERVER_IP

On Windows, use PowerShell (it includes ssh). If you get a key-permissions error on macOS/Linux, run chmod 600 /path/to/YOUR_PRIVATE_KEY first.

Once connected, get the latest system updates:

sudo apt update && sudo apt upgrade -y

Step 4 — Install Docker

Docker is the simplest way to run the app on a server:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker ubuntu

Log out and back in (exit, then SSH in again) so the group change takes effect.

Prefer Node.js instead of Docker? Install it with sudo apt install -y nodejs npm and follow the Node steps from the local guide — then jump to Step 7 for keeping it running.

Step 5 — Upload & start Map Blueprint

From your own computer (not the SSH session), copy the unzipped product folder up to the server:

scp -i /path/to/YOUR_PRIVATE_KEY -r ./map-blueprint ubuntu@YOUR_SERVER_IP:~/

Back in the SSH session, go into the folder and create your settings:

cd ~/map-blueprint
cp .env.example .env
nano .env

Set a strong APP_PASSWORD and a SESSION_SECRET. Generate a secret with:

docker run --rm node:20-alpine node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Then start it:

docker compose up -d

Confirm it's running and listening on port 8080:

docker compose ps

At this point the app is up, but only on the server's internal port 8080. The next step makes it reachable on the web over HTTPS.

Step 6 — Add your domain & free HTTPS

The app speaks plain HTTP and is designed to sit behind something that adds HTTPS. Pick one of these two approaches.

Option A — Cloudflare Tunnel (no open ports, easiest to secure)

1. Add your domain to a free Cloudflare account.
2. On the server, install cloudflared and log in:

   curl -fsSL https://pkg.cloudflare.com/install.sh | sudo bash
   sudo apt install -y cloudflared
   cloudflared tunnel login

3. Create a tunnel and route your subdomain to the app's local port:

   cloudflared tunnel create mapblueprint
   cloudflared tunnel route dns mapblueprint maps.YOURDOMAIN.com

4. Point the tunnel at http://localhost:8080 in its config, then install it as a service so it always runs:

   sudo cloudflared service install

Cloudflare handles the HTTPS certificate automatically and nothing needs to be exposed directly — you can leave ports 80/443 closed.

Option B — Caddy reverse proxy (automatic certificate)

1. Point a DNS A record for maps.YOURDOMAIN.com at YOUR_SERVER_IP (at your domain registrar or DNS provider).
2. Install Caddy on the server.
3. Put this in /etc/caddy/Caddyfile:

   maps.YOURDOMAIN.com {
       reverse_proxy localhost:8080
   }

4. Reload Caddy:

   sudo systemctl reload caddy

Caddy fetches and renews a free Let's Encrypt certificate for you automatically. This needs ports 80 and 443 open (Step 2).

Visit https://maps.YOURDOMAIN.com — you should see the login page. Sign in and share that link with your team.

Step 7 — Keep it running after reboots

The included docker-compose.yml sets restart: unless-stopped, so the Docker container comes back automatically whenever the server reboots — nothing more to do.

If you chose the Node.js path instead of Docker, create a service so it auto-starts. Save this as /etc/systemd/system/map-blueprint.service:

[Unit]
Description=Map Blueprint
After=network.target

[Service]
WorkingDirectory=/home/ubuntu/map-blueprint
Environment=APP_PASSWORD=YOUR_PASSWORD
Environment=SESSION_SECRET=YOUR_LONG_RANDOM_SECRET
Environment=HOST=0.0.0.0
ExecStart=/usr/bin/npm start
Restart=always
User=ubuntu

[Install]
WantedBy=multi-user.target

Then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now map-blueprint.service
sudo systemctl status map-blueprint.service

Security checklist

• Use a strong, unique APP_PASSWORD — it's the only thing gating access to your maps.
• Set a long random SESSION_SECRET so logins stay valid across restarts (and aren't guessable).
• Always reach the app over HTTPS (Step 6), never plain http://YOUR_SERVER_IP:8080 in production.
• Keep the server patched: sudo apt update && sudo apt upgrade -y from time to time.
• Protect your SSH private key and never share it. Consider restricting SSH (port 22) to your own IP in the security list.
• Back up the data/ folder regularly — that's where all your maps live.

Updating to a new version

When you receive an updated build, upload it over the old folder (keep your .env and data/), then:

cd ~/map-blueprint
docker compose up -d --build