veem

Provision a VM and deploy your app in two commands.

veem init    # provision the VM
veem deploy  # ship the app

What it does

veem init connects to a fresh Ubuntu VM and sets it up for production: installs Docker, configures a firewall, creates a dedicated deploy user, and provisions Traefik as a reverse proxy with automatic HTTPS via Let's Encrypt.

veem deploy builds your Docker image locally, transfers it to the VM securely over SSH (no registry required, gzip-compressed for a faster upload), and starts your application using blue/green deployment — bringing up the new version before tearing down the old one so there's zero downtime. (Apps with a persistent volume deploy serialized instead — see Persistent data.) Deployment also includes securely copying your .env file to your VM.

Install

npm install -g veem-cli

Quick start

In your project directory, ensure there's a Dockerfile and the image can be built locally. Then run the following commands:

veem init
veem deploy

Your app will be live at my-app.1-2-3-4.sslip.io with a valid TLS certificate.

Commands

veem init

Provisions a fresh VM for production use.

| Option | Description | |---|---| | --host <ip> | VM IP address | | --ssh-user <user> | SSH user (default: root) | | --ssh-key <path> | Path to SSH private key | | --email <email> | Email for Let's Encrypt |

If any required options are missing, veem init will prompt you interactively.

This command only needs to be run once per VM. If you want to deploy additional apps to the VM, you'll need to set up a .veem.json file manually in the other project's directory.

veem deploy

Builds and deploys your app to the VM.

| Option | Description | |---|---| | --tag <tag> | Image tag (default: current git SHA) | | --host <ip> | VM IP override | | --ssh-user <user> | SSH user override (default: deploy) | | --ssh-key <path> | SSH key path override | | --image <name> | Docker image name override | | --env <suffix> | Upload .env.<suffix> as .env on the VM (e.g. --env prod → .env.prod) |

Utility commands

veem logs

Fetches logs from the deployed container on the VM.

| Option | Description | |---|---| | -C, --container <name> | Container name (default: <appName>-app-1) | | -T, --tail | Follow log output (docker logs -f) | | --ssh-user <user> | SSH user override | | --ssh-key <path> | SSH key path override |

veem ps

Lists all Docker containers on the VM (docker ps -a).

| Option | Description | |---|---| | --ssh-user <user> | SSH user override | | --ssh-key <path> | SSH key path override |

Configuration

veem reads from a .veem.json file in your project root. Options passed via CLI flags take precedence.

{
  "appName": "my-app",
  "appPort": 3000,
  "imageName": "my-app",
  "host": "1.2.3.4",
  "sshUser": "deploy",
  "sshKeyPath": "~/.ssh/id_rsa",
  "letsencryptEmail": "[email protected]",
  "dataPath": "/app/data"
}

Place a .env file in your project root and veem deploy will upload it to the VM automatically.

Persistent data (SQLite, uploads, etc.)

Set dataPath to a directory inside your container and veem will mount a named Docker volume there. The volume survives every deploy and image rebuild, so it's the place to keep a SQLite database or other files that must outlive a release.

{
  "dataPath": "/app/data"
}

Point your app at the mounted path, e.g. in .env:

DATABASE_URL=/app/data/app.db

The volume is named <appName>_data on the VM. Don't rename the ~/apps/<appName> directory on the VM afterward, or Compose will look for a differently-named volume and the data will appear to be gone (it's still there under the old name).

Deploys for apps with a dataPath are serialized, not zero-downtime. SQLite is a single-writer database, so veem stops the old container before starting the new one to guarantee only one container ever writes the file — a brief downtime during each deploy. Apps without a dataPath keep the zero-downtime blue/green rollover.

To deploy with a different env file, pass --env <suffix> and veem will upload .env.<suffix> from your project root in place of .env. For example:

veem deploy --env prod    # uploads .env.prod as .env on the VM
veem deploy --env staging # uploads .env.staging as .env on the VM

If the named file doesn't exist, the deploy fails fast.

License

MIT