farpost

Deploy pet projects to a remote VPS via Docker Compose over SSH. No agents, no daemons — just Docker.

Why farpost?

Most VPS deployment tools either require a server-side agent, a CI/CD pipeline, or complex configuration. farpost does none of that — it connects to your server over SSH and runs docker compose commands remotely, just as you would locally. No setup on the server beyond Docker. No extra services to maintain.

Workflow

1. Develop and test locally with docker compose up
2. Run farpost deploy — builds the image on the server and starts containers
3. Check logs with farpost logs or open farpost dashboard to monitor services
4. Push a fix? Just run farpost deploy again — services are rebuilt and restarted automatically

Install

npm install -g farpost

Requires Docker with the Compose plugin on the server (docker compose version must work).

Quick start

Create farpost.json in your project root:

{
  "host": "[email protected]",
  "name": "my-app",
  "composeFile": "./docker-compose.yml",
  "environment": {
    "NODE_ENV": "production"
  }
}

Deploy:

farpost deploy

Configuration

| Field | Required | Default | Description | |---|---|---|---| | host | ✅ | — | SSH host ([email protected]) | | name | ❌ | directory name | Docker Compose project name (-p flag) | | composeFile | ❌ | docker-compose.yml | Path to compose file (relative to config file) | | environment | ❌ | {} | Env vars passed to Compose via --env-file | | preDeployUpload | ❌ | — | Files to upload via scp before deploy. Keys are local paths (relative to config file), values are absolute remote paths. |

Variables from environment are passed to Compose via --env-file. To use them in docker-compose.yml, reference them with ${VAR_NAME} syntax:

services:
  app:
    build: .
    restart: unless-stopped
    environment:
      - NODE_ENV=${NODE_ENV}
      - DATABASE_URL=${DATABASE_URL}
      - SECRET_KEY=${SECRET_KEY}
    ports:
      - "${PORT}:3000"
    volumes:
      - app-data:/app/data

volumes:
  app-data:

With the corresponding farpost.json:

{
  "host": "[email protected]",
  "name": "my-app",
  "composeFile": "./docker-compose.yml",
  "environment": {
    "NODE_ENV": "production",
    "DATABASE_URL": "postgres://user:pass@db:5432/myapp",
    "SECRET_KEY": "supersecret",
    "PORT": "8080"
  }
}

Use --config to point to a different config file:

farpost --config ./configs/prod.json deploy

Uploading files before deploy

When using bind mounts in docker-compose.yml, the mounted path must exist on the server:

volumes:
  - /home/user/app/config.json:/app/config.json  # server path, not local

Use preDeployUpload to copy local files to the server automatically before each deploy:

{
  "host": "[email protected]",
  "preDeployUpload": {
    "./config.json": "/home/user/app/config.json",
    "./secrets/rclone.conf": "/home/user/.config/rclone/rclone.conf"
  }
}

farpost runs mkdir -p on the remote directory and uploads via scp before deploying. If any upload fails, the deploy is aborted.

Files are uploaded on every farpost deploy. For files that rarely change, you can copy them manually once with scp instead.

Commands

| Command | Description | |---|---| | farpost deploy | docker compose up -d --build --remove-orphans | | farpost deploy --no-cache | Build without layer cache | | farpost pull [service] | Pull latest images for all services or one | | farpost start [service] | Start all services or one | | farpost stop [service] | Stop all services or one | | farpost restart [service] | Restart all services or one | | farpost logs [service] | Follow logs (Ctrl+C to exit) | | farpost ps | Show container statuses | | farpost dashboard | Interactive TUI | | farpost init | Create a farpost.json stub in the current directory |

Example output

farpost deploy:

 => [app] FROM node:20
 => [app] COPY . .
 => [app] RUN npm ci
 ...
 ✔ Container my-app-app-1  Started

farpost logs app:

my-app-app-1  | Server listening on port 3000
my-app-app-1  | Connected to database
my-app-app-1  | GET /health 200 12ms

farpost dashboard:

  farpost  my-app  [email protected]  14:32:01
──────────────────────────────────────────────────

  SERVICE              STATUS
  [whole project]
▶ app                  running
  db                   running

──────────────────────────────────────────────────
  [↑↓] navigate  [u] up  [d] down  [r] restart  [space] refresh  [q] quit

Requirements

• Node.js >= 18
• SSH access to the server
• Docker with Compose plugin on the server