Install plamotrack with Docker

plamotrack runs on a computer or server you control. Each release comes with a small set of files that tell Docker exactly which tested images to run. Docker then starts the app and its database together, so you don’t need to install Python, Node.js or Postgres yourself, and nothing is built on your computer. Allow time to install Docker. After that, setup is a short sequence of commands, and the first start takes a minute or two while Docker downloads the images.

Before you start

You need Docker with Docker Compose, curl to download the release files, a web browser and a plain-text editor.

Windows
macOS
Linux

Install Docker Desktop for Windows and follow its WSL 2 setup instructions. Install Git for Windows as well. plamotrack doesn’t use Git itself, but Git for Windows includes Git Bash, a terminal that runs the commands in this guide exactly as written and includes curl.Start Docker Desktop and wait until its engine is running. Open Git Bash from the Start menu. Run the commands in this guide there.

Install Docker Engine and the Docker Compose plugin, or use Docker Desktop. Install curl too if your distribution doesn’t include it (sudo apt install curl on Debian and Ubuntu).Open your distribution’s Terminal. Follow Docker’s installation instructions for starting its service and running Docker commands as your user.

A terminal is the window where you enter commands. Copy one line at a time, press Enter, and wait for it to finish before entering the next. These commands should show version information:

docker --version
docker compose version
curl --version

If a command is not found, finish installing that prerequisite and reopen the terminal.

Install plamotrack

These steps install v0.6.0-alpha. If the releases page lists a newer version, use its number in place of v0.6.0-alpha.

Make a folder for plamotrack

In your terminal, run:

mkdir -p ~/plamotrack
cd ~/plamotrack

This creates a plamotrack folder in your home folder and moves your terminal into it.Run every remaining command from this folder. If you close the terminal and come back later, run cd ~/plamotrack first. Keep the folder and its name: Docker Compose uses the folder’s name to name the volume that holds your database. You’ll use the folder to stop, start and update the app.

Download the release files

Run this as one line:

for f in docker-compose.yml env.example plamotrack-gunpla.zip release.json SHA256SUMS; do curl -fsSLO "https://github.com/DeusMaximus/plamotrack/releases/download/v0.6.0-alpha/$f"; done

Then check that the files arrived intact:

Windows or Linux
macOS

sha256sum -c SHA256SUMS

shasum -a 256 -c SHA256SUMS

Each of the four files should say OK. If any says FAILED, delete the folder’s contents and download them again. Don’t start the app from files that fail this check.

File	What it is
`docker-compose.yml`	Which images to run, each pinned to the exact tested build
`env.example`	The settings template you copy in the next step
`plamotrack-gunpla.zip`	The Gunpla skill for your AI assistant, if you use one: see Agent Skills
`release.json`, `SHA256SUMS`	The release’s record and the checksums you just checked

Create your settings file

Copy the settings template:

cp env.example .env

The new .env file is in the plamotrack folder. Its name starts with a dot, so your file manager may hide it.

Windows
macOS
Linux

From the same Git Bash window, open the file in Notepad:

notepad .env

Save the existing file as .env, without adding .txt. To find it in File Explorer, open your home folder and then plamotrack; enable File name extensions and Hidden items in the View options if needed.

From Terminal, open the existing file in TextEdit:

open -e .env

Keep it as plain text and save it under its existing name. In Finder, Command–Shift–. shows hidden files.

Open .env in a plain-text editor. Most file managers use Ctrl–H to show hidden files.If you have nano installed, you can edit it in the terminal:

nano .env

In nano, press Ctrl–O, then Enter to save, and Ctrl–X to close.

Find this line:

POSTGRES_PASSWORD=change-me

Replace change-me with a long, unique database password. A password manager can generate one; using letters and digits avoids special-character handling in this file. Keep the other settings at their defaults for this local installation, then save.This is the database password. The app uses it to connect to Postgres. You will choose a separate owner password in your browser during First Run.

Set this before the first start. Editing it later does not change the password inside an existing database and can prevent the app from connecting.

Start the app

Back in the terminal, run:

docker compose up -d --no-build --wait

Docker downloads the images, prepares the database and starts the services. No login to any registry is needed.Wait for the command to finish successfully and return to your terminal prompt. You can check the containers with:

docker compose ps -a

The db, api and web services should be running. The migrate service prepares the database and then stops: Exited (0) is its successful result.If startup fails, read the error before continuing. The troubleshooting guide covers common problems.

Claim your instance

Open http://localhost:8080 in a browser on the same computer. You should see Set up plamotrack.Continue to First Run to find the setup token, choose your owner password and add your first kit.

Where the app runs

By default, only this computer can reach plamotrack. The computer and Docker need to stay running while you use it.

Address	Purpose
`http://localhost:8080`	The app
`http://localhost:8080/api/kits`	An example REST API route; authentication is required
`http://localhost:8080/mcp/`	The endpoint for compatible AI assistants

Docker publishes one app port. The API and database containers communicate inside the Docker network. To use plamotrack from another device, follow Local & LAN. For access over the internet, choose a documented HTTPS deployment or Cloudflare Tunnel.

Change the port

If another app already uses port 8080, open .env, change WEB_PORT, and save:

WEB_PORT=9090

Then apply the change from your plamotrack folder:

docker compose up -d --no-build --wait

Open http://localhost:9090 instead, and use that port in the First Run guide too.

Use an existing Postgres server

This is optional. The default installation already includes a database. If you manage a separate Postgres server, DATABASE_URL in .env can point the API and migrations at it. See the configuration reference. The bundled Compose file still starts its own db service, so setting DATABASE_URL alone does not remove that container or its configuration requirements.

Get Started

Using plamotrack

Deployment

Authentication

AI & MCP

Configuration & Maintenance

Install plamotrack with Docker

Before you start

Install plamotrack

Where the app runs

Change the port

Use an existing Postgres server

​Before you start

​Install plamotrack

​Where the app runs

​Change the port

​Use an existing Postgres server

Before you start

Install plamotrack

Where the app runs

Change the port

Use an existing Postgres server