> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gunp.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Install plamotrack with Docker

> Install Docker and Git, create your settings file, and start plamotrack on Windows, macOS or Linux. Then claim your instance and add your first kit.

plamotrack runs on a computer or server you control. Docker starts the app and its database together, so you do not need to install Python, Node.js or Postgres yourself.

Allow time to install the prerequisites and download and build the images. With everything already installed, setup is a short sequence of commands; the first build can take longer than three minutes, depending on your computer and connection.

## Before you start

You need **Docker with Docker Compose**, **Git**, a web browser and a plain-text editor.

<Tabs>
  <Tab title="Windows">
    Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) and follow its WSL 2 setup instructions. Install [Git for Windows](https://git-scm.com/install/windows), which includes **Git Bash**.

    Start Docker Desktop and wait until its engine is running. Open **Git Bash** from the Start menu. Run the commands in this guide there.
  </Tab>

  <Tab title="macOS">
    Install [Docker Desktop for Mac](https://docs.docker.com/desktop/setup/install/mac-install/) and [Git](https://git-scm.com/install/mac).

    Start Docker Desktop and wait until its engine is running. Open **Terminal** from **Applications → Utilities**. Run the commands in this guide there.
  </Tab>

  <Tab title="Linux">
    Install [Docker Engine](https://docs.docker.com/engine/install/) and the [Docker Compose plugin](https://docs.docker.com/compose/install/linux/), or use Docker Desktop. Install [Git for your distribution](https://git-scm.com/install/linux).

    Open your distribution's **Terminal**. Follow Docker's installation instructions for starting its service and running Docker commands as your user.
  </Tab>
</Tabs>

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:

```bash theme={null}
git --version
docker --version
docker compose version
```

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

## Install plamotrack

<Steps>
  <Step title="Download the project">
    In your terminal, run:

    ```bash theme={null}
    cd ~
    git clone https://github.com/DeusMaximus/plamotrack.git
    cd plamotrack
    ```

    This creates a `plamotrack` folder in your home folder. The final command 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: you will use it to stop, start and update the app.
  </Step>

  <Step title="Create your settings file">
    Copy the supplied example:

    ```bash theme={null}
    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.

    <Tabs>
      <Tab title="Windows">
        From the same Git Bash window, open the file in Notepad:

        ```bash theme={null}
        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.
      </Tab>

      <Tab title="macOS">
        From Terminal, open the existing file in TextEdit:

        ```bash theme={null}
        open -e .env
        ```

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

      <Tab title="Linux">
        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:

        ```bash theme={null}
        nano .env
        ```

        In nano, press **Ctrl–O**, then **Enter** to save, and **Ctrl–X** to close.
      </Tab>
    </Tabs>

    Find this line:

    ```dotenv theme={null}
    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](/first-run).

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Start the app">
    Back in the terminal, run:

    ```bash theme={null}
    docker compose up -d --build --wait
    ```

    Docker downloads dependencies, builds the app, prepares the database and starts the services. Keep `--build` in the command, including on the first run.

    Wait for the command to finish successfully and return to your terminal prompt. You can check the containers with:

    ```bash theme={null}
    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](/configuration/troubleshooting) covers common problems.
  </Step>

  <Step title="Claim your instance">
    Open [http://localhost:8080](http://localhost:8080) in a browser on the same computer. You should see **Set up plamotrack**.

    Continue to [First Run](/first-run) to find the setup token, choose your owner password and add your first kit.
  </Step>
</Steps>

## 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](/deployment/local-and-lan). For access over the internet, choose a documented [HTTPS deployment](/deployment/vps-caddy) or [Cloudflare Tunnel](/deployment/cloudflare-tunnel).

## Change the port

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

```dotenv theme={null}
WEB_PORT=9090
```

Then apply the change from your `plamotrack` folder:

```bash theme={null}
docker compose up -d --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](/configuration/env-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.