Setting up nodes

This guide adds a node to up and confirms it can build and run your services. It assumes you have a control node running and the up CLI configured against it.

1. Prepare a node

Provision a Linux host from your favourite VPS provider with:

• Podman (recommended) or Docker installed.
• For podman, prefer setting up a non-root deploy user or similar. For Docker, you will need to have a root user.
• You can connect to said host using SSH.

Note the host IP, the SSH user, the SSH port, and the path to your private key (Prefer setting up private keys instead of password).

2. Declare the node

Add the node to up.yaml so up knows about it. See the node configuration reference for every field:

nodes:
  - name: edge-1
    roles:
      - deploy
    host: 203.0.113.10
    user: root
    port: 22
    key_path: ~/.ssh/id_ed25519

  - name: builder-1
    roles:
      - build
    host: 203.0.113.11
    user: root

The example above sets up 2 different nodes, one being a build node (it will build our applications), another being a deploy node (it will run the built applciations).

3. Provision it

For the first time, run up node add so up can reach the host and install itself on that node:

up node add ssh://root@203.0.113.10 -i ~/.ssh/id_ed25519 --name edge-1

This connects over SSH, ensures Docker or Podman is present, and registers the node with the control node.

A node with the build role also needs git on its PATH to clone git sources, alongside rootlesskit and buildkitd for the build daemon. When one of these is missing, up node add prints a warning but still registers the node: builds start failing only when a git source is deployed, so install the missing tools before use.

4. Verify

Confirm the node appears and is ready with up node list:

up node list

The new node should be listed with its roles and a ready status. If it is not ready, check SSH connectivity and that the key at key_path unlocks the host.

5. Use it

Reference the node by name from services:

services:
  - name: api
    source:
      type: git
      url: git@github.com:org/api.git
    build:
      type: dockerfile
      node: builder-1                   # Here we are explicitly specifying the node which runs our builds
      output_registry: ghcr
    port: 8080

Then up apply builds on builder-1 and deploys onto any deploy node.

6. Change a node’s roles

A node’s roles are read live from the node itself. Edit the roles list in up.yaml and run up apply: up pushes the new set to the node over the node config API, the node applies it without a restart, and up reads the node back to confirm.

You can also change one node directly, which is useful when a node is not part of the current project config:

up node config set roles build,deploy --node edge-1

The node’s token and database path are deliberately local-only. Changing node_token remotely would lock the control node out of that node, and changing db_path remotely would point the agent at a different database on its next start. Set those on the node itself with the local form of the command.

Removing the deploy role from a node that still hosts an environment is refused with an error naming the environments. Move or remove them first.

A node that cannot be reached is reported as offline and skipped during build and deploy placement. Fix connectivity and read the node again to reconcile its roles.