Map Blueprint

Tier 2 · Advanced guide

Host Map Blueprint on a cloud server

Put your instance on an always-on server, a computer that runs in a data centre 24/7, so remote teammates can reach it from anywhere, with your own web address and free HTTPS (the padlock that encrypts the connection). This guide uses Oracle Cloud's Always-Free tier, which can run Map Blueprint at no monthly cost, but the same steps work on any Ubuntu cloud server.

What you'll end up with: a small Linux server running Map Blueprint around the clock, reachable at something like https://maps.yourdomain.com, protected by your team password, and restarting itself automatically after reboots. Plan on about 20–30 minutes. Wherever you see YOUR_… below, replace it with your own value.

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

A few words you'll meet: a server is a computer that runs all the time so others can connect; SSH is a secure way to type commands on that remote computer from your own; a domain is your web address (like yourdomain.com); DNS is the internet's address book that points a domain at a server; HTTPS is the encrypted, padlocked version of a web address; a reverse proxy and a tunnel are two ways to put HTTPS in front of the app. Don't worry, each step below tells you exactly what to do.

Step 1, Create a free server

  1. Sign up at Oracle Cloud Free Tier and log in to the console (Oracle's website for managing your servers).
  2. Go to Compute → Instances → Create instance. An "instance" is simply Oracle's word for a server.
  3. Choose an Always-Free-eligible shape (the server's size, "shape" is Oracle's word for it). Either is fine: VM.Standard.E2.1.Micro or an Ampere Arm shape (which has more memory). Keep the default Ubuntu image, Ubuntu is the version of Linux this guide uses.
  4. Under Add SSH keys, choose Generate a key pair for me and download the private key, this small file is what proves it's you when you log in, so keep it somewhere safe. (Already have your own key? Paste its public half instead.)
  5. Click Create. When the server is running, copy its Public IP address (the server's number on the internet), this guide calls it YOUR_SERVER_IP.

Step 2, Open the firewall

A firewall blocks unexpected network connections. Oracle blocks incoming web traffic by default, so you need to allow it on the two standard web ports, 80 (plain web) and 443 (secure web):

  1. Open your instance → click its Virtual Cloud Network / subnet → Security Lists → the default list. (This is Oracle's firewall.)
  2. Add Ingress Rules ("ingress" just means incoming) that allow TCP from 0.0.0.0/0 (meaning "from anywhere") to ports 80 and 443.
Ubuntu on Oracle also has its own local firewall. After you connect in Step 3, allow the same two ports by pasting these three lines (each line is one command; the third saves the rule so it survives reboots): 
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
If you use the Cloudflare Tunnel option in Step 5, you can skip opening ports 80/443 entirely.

Step 3, Connect to the server

Now you'll log in to the server and type commands on it from your own computer, using SSH. Open a terminal (on Windows, use PowerShell, it already includes ssh) and run this, pointing -i at the private key file you downloaded:

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

On Mac or Linux, if you get a "permissions are too open" error about the key, run chmod 600 /path/to/YOUR_PRIVATE_KEY first, that tightens the file so only you can read it, which SSH requires.

Once you're connected (your command prompt now shows the server), install the latest system updates:

sudo apt update && sudo apt upgrade -y

sudo means "run this as administrator"; apt is Ubuntu's built-in app installer.

Step 4, Upload and start Map Blueprint

There's nothing to install on the server, no Docker, no Node, no .env. It's a single self-contained program. From your own computer (a new terminal window, not the SSH session), run this from the folder where you unzipped the download to copy the Linux program up to the server. scp is "secure copy", it sends a file over the same secure SSH connection:

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

Back in the SSH session, make the program runnable and start it. HOST=0.0.0.0 tells it to accept connections from outside, so the HTTPS step next can reach it:

chmod +x ~/map-blueprint-linux
HOST=0.0.0.0 ~/map-blueprint-linux

It's now listening on port 8080. You'll set your team password from the browser once HTTPS is in place (next step). For now, press Ctrl-C to stop it, Step 6 turns it into a service that runs 24/7.

config.json and your data/ maps are created right next to the program in your home folder (~/). All settings live on the in-app Settings page, there are no files to edit.

Step 5, Add your domain and free HTTPS

The app speaks plain HTTP and is designed to sit behind something that adds HTTPS (the encrypted padlock). Pick one of these two approaches, Option A is the easiest to secure.

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

A tunnel connects your server out to Cloudflare, so visitors reach the app through Cloudflare without any ports being open on your server.

  1. Add your domain to a free Cloudflare account.
  2. On the server, install cloudflared (Cloudflare's tunnel tool) 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 point your chosen web address at the app's local port: 
    cloudflared tunnel create mapblueprint
cloudflared tunnel route dns mapblueprint maps.YOURDOMAIN.com
  4. Tell the tunnel to send traffic to http://localhost:8080 in its config, then install it as a background service so it always runs: 
    sudo cloudflared service install

Cloudflare creates and renews the HTTPS certificate for you automatically, and nothing on your server is exposed directly, you can leave ports 80/443 closed.

Option B, Caddy reverse proxy (automatic certificate)

Caddy is a tiny web server that sits in front of the app, adds HTTPS, and forwards visitors to it, that's what a reverse proxy does.

  1. Point a DNS A record for maps.YOURDOMAIN.com at YOUR_SERVER_IP. (An "A record" is the DNS entry that maps a name to a server's IP, set it at your domain registrar or DNS provider.)
  2. Install Caddy on the server.
  3. Put this in the file /etc/caddy/Caddyfile (it tells Caddy: serve this address, and forward visitors to the app on port 8080): 
    maps.YOURDOMAIN.com {
    reverse_proxy localhost:8080
}
  4. Reload Caddy so it picks up the change: 
    sudo systemctl reload caddy

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

Map Blueprint automatically marks its login cookie Secure once requests arrive over HTTPS (it reads the X-Forwarded-Proto header that both options above set), so logins are protected with no extra setup.

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

Optional, lock it down with Cloudflare Zero Trust

Want a second, stronger lock? Cloudflare Zero Trust "Access" puts a login screen in front of your app, so strangers never even reach Map Blueprint, Cloudflare checks who you are first. It works best with Option A (the Cloudflare Tunnel) above, and it lets you grant access person-by-person by email instead of sharing one password. It's free for small teams.

  1. In the Cloudflare dashboard, open Zero Trust (set up the free plan if it's your first time).
  2. Go to Access → Applications → Add an application → Self-hosted.
  3. Set the application's domain to the same web address the tunnel serves (maps.YOURDOMAIN.com).
  4. Add an Access policy that allows just your teammates' email addresses (or a whole email domain like @yourstudio.com), then save.
  5. Now visiting the site shows a Cloudflare login that emails a one-time PIN code (or uses Google / GitHub sign-in). Only approved people get through to the app.

This is the same kind of identity gate the makers of Map Blueprint use on their own internal map. Even if someone learns your URL, they can't load the app without passing the identity check, ideal for a private studio map.

Step 6, Keep it running after reboots

Finally, turn the app into a service so it starts on boot and restarts itself if it ever stops. (A "service" is a program Linux looks after in the background.) Save the text below as the file /etc/systemd/system/map-blueprint.service:

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

[Service]
WorkingDirectory=/home/ubuntu
Environment=HOST=0.0.0.0
ExecStart=/home/ubuntu/map-blueprint-linux
Restart=always
User=ubuntu

[Install]
WantedBy=multi-user.target

Then switch it on, reload the service list, enable and start it, and check it's running:

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

WorkingDirectory=/home/ubuntu keeps config.json and your data/ maps in the home folder, next to the program. Now open https://maps.YOURDOMAIN.com, complete the first-run Setup screen, and set your team password right away. (Prefer to set it in advance? Add Environment=APP_PASSWORD=YOUR_PASSWORD to the service file.)

Security checklist

Updating to a new version

When you get an updated program, stop the service, replace the program file, and start it again, your config.json and data/ maps are left untouched. Upload the new map-blueprint-linux from your computer (with scp, as in Step 4), then on the server run:

sudo systemctl stop map-blueprint.service
chmod +x ~/map-blueprint-linux
sudo systemctl start map-blueprint.service

Next → Tier 3 · Deep reference: the map file format