Skip to content

Single-Node Clusters

A single-node cluster is a Docker Swarm cluster with only the leader (manager) node and no worker nodes. Appliku treats this case specially: when the leader is also the build server and no container registry is configured, deployments stay entirely local — no image push, no image pull, no registry credentials required.

When to Use

A single-node cluster is a good fit when you want cluster-only features (replicas, gradual stack updates, the option to scale out later) without setting up a container registry yet. Many users may never need to grow past a single node.

If you know up front you will run multiple nodes, configure a container registry from the start.

How It Works

Local-only image mode is used when all of the following are true at deploy time:

  • The cluster has no worker nodes (is_cluster_worker=True servers).
  • No registry credentials are configured for the cluster.
  • A build server is assigned to the deployment.
  • The build server is the cluster's primary manager (leader).

If any of these conditions is not met — a worker exists, registry credentials are present, or a separate build server is in use — Appliku falls back to the standard registry-backed flow.

What's the same as a registry-backed cluster

  • Application configuration, environment variables, processes, and appliku.yml work identically.
  • docker stack deploy --prune is still used, so obsolete services are cleaned up on each deploy.
  • One-off commands and release commands run the same way and use the same image.
  • Replicas, scaling, and gradual stack updates work as usual (within the limits of a single node).

What's different

  • The image is built on the leader and tagged as appliku-{application.name}:{deployment.pk} — there is no registry host in the tag.
  • docker login and docker image push are skipped.
  • docker stack deploy runs with --resolve-image=never instead of --with-registry-auth. This tells Swarm to use the local image without trying to resolve the tag against Docker Hub.
  • Temporary services for one-off / release commands also use --resolve-image=never and omit --with-registry-auth.
  • Deployment logs explicitly state which mode is in use ("local-only image mode" vs "registry-backed").

Adding a Worker Node Later

If you grow into a multi-node cluster after running locally for a while:

  1. The locally deployed services keep running on the leader — they are not interrupted.
  2. The next deployment fails immediately with a message asking you to configure registry credentials before redeploying. Worker nodes cannot pull a local image, so deploys must switch to registry-backed mode before any new build can roll out across the cluster.
  3. Once you add registry credentials, the next deployment uses the standard registry-backed flow. The build is pushed, the worker can pull it, and the service is redeployed across the cluster.

This is intentional: Appliku does not silently migrate locally-built images to a registry, because the previously-built image was never tagged for one. You must redeploy.

Image Retention

Local-only mode relies on the leader's existing scheduled Docker clean up (the server's "Full clean up schedule") to remove old images. The clean up removes all images that no container uses. There is no separate retention policy for local tags. As a consequence, rollback to an older deployment may not be possible if its image has already been pruned. If rollback durability matters to you, configure a registry — registry images are not pruned by the leader's local cleanup.

Limitations

  • All limitations from Cluster Limitations & Gotchas still apply (no persistent volumes, databases must be on standalone servers, etc.).
  • Local-only mode is only available on single-node clusters where the leader is the build server. If you use a separate standalone build server, you need a registry — the build host is not the runtime host.
  • Custom Docker Compose overrides may reference images Appliku does not build. Those remain user-managed in either mode.

Next Steps