Skip to main 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 system prune -f -a to clean up old images. 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​