Get started

Install

Install Dezfil with Docker, Docker Compose or from source, create the admin account, and keep the instance running day to day.

What you need

For Docker or Docker Compose: Docker, on a 64-bit Intel, AMD or Arm machine. Compose also needs the docker compose command.
For a development checkout: Node.js 24 or newer, npm and git.

Each release is published as the image ghcr.io/dezfil/dezfil, for linux/amd64 and linux/arm64.

Install

Docker is the quickest start. Docker Compose keeps the setup in a file, and starts Dezfil again after a crash or a Docker restart. From source is for working on the code.

Docker

docker run -d --name dezfil -p 127.0.0.1:3000:3000 -v dezfil-data:/data ghcr.io/dezfil/dezfil

-p 127.0.0.1:3000:3000 serves Dezfil on port 3000 of this machine only. To use another port, change the first 3000.
-v dezfil-data:/data keeps everything Dezfil stores in the dezfil-data volume. Without it, a new container starts empty.
--name dezfil is the name the everyday commands use.
ghcr.io/dezfil/dezfil is the latest release. To run one version, add its tag, as in ghcr.io/dezfil/dezfil:<VERSION>.

The first docker run downloads the image, which takes a few minutes. Dezfil should be ready within 30 seconds of starting. Check it:

curl http://localhost:3000/api/health

{"status":"ready"}

Then open http://localhost:3000.

Docker Compose

Make a folder for the Compose file:

mkdir dezfil
cd dezfil

Save this file as compose.yaml in the dezfil folder:

services:
  dezfil:
    image: ghcr.io/dezfil/dezfil
    container_name: dezfil
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - dezfil-data:/data
    restart: unless-stopped

volumes:
  dezfil-data:
    name: dezfil-data

Start Dezfil:

docker compose up -d

image: ghcr.io/dezfil/dezfil runs the latest release. To run one version, add its tag, as in ghcr.io/dezfil/dezfil:<VERSION>.
127.0.0.1:3000:3000 serves Dezfil on port 3000 of this machine only. To use another port, change the first 3000.
dezfil-data:/data keeps everything Dezfil stores in the dezfil-data volume.
restart: unless-stopped starts Dezfil again after a crash or a Docker restart, unless you stopped it.

For an instance that lasts, with its keys and backups, see Docker Compose.

The first start downloads the image, which takes a few minutes. Dezfil should be ready within 30 seconds of the container starting. Check it:

curl http://localhost:3000/api/health

{"status":"ready"}

Then open http://localhost:3000.

From source

Use this to work on Dezfil’s code. It runs a development server that reloads as you edit.

git clone https://github.com/Dezfil/Dezfil.git
cd Dezfil
npm ci
npm run dev

npm ci installs the exact package versions the lockfile pins.
npm run dev serves Dezfil on port 3000 and keeps your data in ./data. Set PORT for another port, DEZFIL_DATA_DIR for another folder.
npm run dev listens on every network interface. Run npm run dev -- -H 127.0.0.1 to keep it on this machine.

In another terminal, check that Dezfil is ready:

curl http://localhost:3000/api/health

{"status":"ready"}

Then open http://localhost:3000.

To stop Dezfil, press Ctrl+C in its terminal. To upgrade, stop it, run git pull and npm ci, then npm run dev again. To back up, stop it and copy the data folder.

A checkout lacks two programs the container brings, tippecanoe for the tiles of large layers and Chromium for the map pictures the server draws, and Development setup shows how to add them.

To build the container image from your checkout, run docker build -t dezfil . in it. Then use dezfil in place of ghcr.io/dezfil/dezfil in the Docker commands.

Development setup covers the rest: the checks, the tests and what they need.

If the check answers Internal Server Error or unready, or nothing at all, the logs say why: run docker logs dezfil or docker compose logs, or read the terminal that runs npm run dev. See Troubleshooting.

First run

The setup page, titled Create the first account, with Name, Email and Password fields and a Create account button

Open http://localhost:3000. Dezfil shows Create the first account. On a server, run ssh -L 3000:127.0.0.1:3000 <YOUR_SERVER> on your computer first, then open the address there.
Fill in Name, Email and Password. The password needs at least 8 characters, and very common passwords are refused.
Click Create account. You should see Home, signed in as the admin.

To add people, open Users in the side menu and click Invite. See Users.

Everyday commands

Docker

Task	Command
Stop	`docker stop dezfil`
Start	`docker start dezfil`
See the logs	`docker logs -f dezfil`
Check health	`curl http://localhost:3000/api/health` answers `{"status":"ready"}`
Back up	Stop Dezfil, then copy the `dezfil-data` volume with the commands in Back up and restore.
Upgrade	Follow Upgrade: it downloads the new version, backs up, replaces the container and keeps a way back.

Docker Compose

Run these in the folder that holds compose.yaml.

Task	Command
Stop	`docker compose stop`
Start	`docker compose start`
See the logs	`docker compose logs -f`
Check health	`curl http://localhost:3000/api/health` answers `{"status":"ready"}`
Back up	Stop Dezfil, then copy the `dezfil-data` volume with the commands in Back up and restore.
Upgrade	Follow Upgrade: it downloads the new version, backs up, replaces the container and keeps a way back.

A new version updates the stored data when it starts. To go back, restore your backup and run the version that made it, as Go back to the old version shows.

Next steps

Your first map: add data and build a map.
Reverse proxy and HTTPS: serve Dezfil under your own domain.
Configuration: the settings that change how your instance runs.
Back up and restore: back up and restore the data volume.
Upgrade: move to a new version and keep your data.
What leaves the instance: what your instance sends out, and what to settle before other people use it.

View this page's source on GitHub

Dezfil · Apache-2.0docs from 7439201b