Search docs.molo17.com

    Deploy Gluesync on Docker Swarm

    This page explains how to install Gluesync as a Docker Swarm stack with the Swarm kit, and what Gluesync Conductor does differently when it manages a Swarm stack instead of a Docker Compose project.

    The Swarm kit deploys a stack named gluesync. There are two variants:

    • Linux: the gluesync-docker-swarm directory of the kit. It runs on one node or on several, with Linux containers.

    • Windows Server 2022: the gluesync-docker-swarm-windows directory of the kit. It runs on a single node, with Windows containers.

    The kit from Get Gluesync is the source of truth. Its docker-stack.yml contains the image versions selected for your release, and its shared directory contains your licence and security files. Do not replace them with a stack file from another installation.

    What is in the stack

    Service Role

    reverse-proxy

    Traefik. Publishes ports 80 and 443 (80 redirects to 443) and routes requests to the other services.

    gluesync-core-hub

    Gluesync Core Hub and its web UI.

    gluesync-chronos

    Gluesync Chronos.

    prometheus

    Metrics storage, served under /prometheus.

    grafana

    Dashboards, served under /grafana. Dashboards and datasources are built into the image.

    gluesync-conductor

    Lists, restarts and updates the services of the stack. See Conductor in Swarm mode.

    Core Hub runs as a single replica. It has no clustering, so scaling it does not make it highly available.

    The kit does not deploy agents. Add them from Core Hub after the platform is running: Conductor adds each agent to docker-stack.yml and deploys it.

    The gluesync-conductor service needs Conductor 0.14.0 or later. A kit packaged when only an older Conductor was available ships without it: the stack works, but you update the services by editing the image tags in docker-stack.yml and running the deploy script again.

    Install on Linux

    Node roles

    The Linux kit uses two node roles. One machine can have both:

    Manager

    A Swarm manager that holds the kit directory. It runs Traefik and Conductor.

    Data node

    The node labelled gluesync.data=true. It holds all persistent data under GLUESYNC_DATA_ROOT (default /var/lib/gluesync-swarm) and runs Core Hub, Chronos, Prometheus and Grafana.

    Requirements

    • Docker Engine 23 or later, with Swarm mode, on every node.

    • Between the nodes: 2377/tcp to the managers, 7946/tcp and 7946/udp, and 4789/udp. See Docker’s Swarm ports.

    • Ports 80 and 443 free on the manager. To use other ports, set TRAEFIK_HTTP_PORT and TRAEFIK_HTTPS_PORT in .env.

    Steps

    1. Create the swarm on the manager and join the other nodes:

      docker swarm init                # on the manager
docker swarm join-token worker   # prints the join command for the other nodes

    2. Copy the gluesync-docker-swarm directory to the data node and prepare it, as root:

      sudo ./prepare-host.sh

      The script creates the data folders, copies the licence, certificates and configuration from shared/ and bootstrap-core-hub.json into GLUESYNC_DATA_ROOT, and labels the node gluesync.data=true. When the data node is not a manager, the script prints the label command to run on a manager.

    3. On the manager that holds the kit directory, deploy the stack:

      ./deploy.sh

      The script creates .env from .env.example, stores the absolute path of the kit directory in it, labels the manager gluesync.kit=true and runs docker stack deploy.

    4. Check that the services are running:

      docker stack services gluesync

    5. Open https://<manager address>/. The default Core Hub credentials are admin / admin; replace them after the first sign-in. Grafana is at /grafana (admin / password, set in .env). The certificate is self-signed, so the browser shows a warning the first time.

    To run everything on one machine, run docker swarm init, sudo ./prepare-host.sh and ./deploy.sh on it.

    Persistence

    All data (Core Hub, Chronos, Prometheus, logs and the shared configuration) lives in host folders on the data node, under GLUESYNC_DATA_ROOT. Swarm named volumes are local to a node: a task rescheduled onto another node would start with an empty volume. For this reason the stateful services are pinned to the node labelled gluesync.data=true and use bind mounts.

    Back up GLUESYNC_DATA_ROOT on the data node. See Backup and restore.

    Install on Windows Server 2022

    The Windows kit runs every service on a single node: the Swarm manager that holds the kit directory. The services keep their configuration, data and logs in folders of that directory.

    Requirements

    • Windows Server 2022 (build 20348) with the latest cumulative update. On the unpatched evaluation build (20348.587), Swarm routes neither service addresses nor published ports. The kit was tested on build 20348.5622.

    • The Containers feature and Docker Engine for Windows Server, running as a service. The images are ltsc2022 images and run with process isolation.

    • In a Hyper-V virtual machine, MAC address spoofing turned on for the VM network adapter, which overlay networking needs. On the Hyper-V host, run Set-VMNetworkAdapter -VMName <vm> -MacAddressSpoofing On.

    • Ports 80 and 443 free on the server. To use other ports, set TRAEFIK_HTTP_PORT and TRAEFIK_HTTPS_PORT in .env.

    Steps

    Open PowerShell as Administrator in the gluesync-docker-swarm-windows directory.

    1. Prepare the server:

      .\prepare-host.ps1

      The script checks the Windows build, the Containers feature and Docker, creates the folders the stack uses, opens the published and Swarm ports in the firewall, pulls the images, creates the swarm (docker swarm init) and labels the node gluesync.kit=true. To choose the address the swarm uses, pass -AdvertiseAddress <ip>.

    2. Deploy the stack:

      .\deploy.ps1

      The script creates .env from .env.example, stores the absolute path of the kit directory in it and runs docker stack deploy.

    3. Check that the services are running:

      docker stack services gluesync

    4. From another machine, open https://<server address>/. The default Core Hub credentials are admin / admin; replace them after the first sign-in. Grafana is at /grafana (admin / password, set in .env). The certificate is self-signed, so the browser shows a warning the first time.

      On Windows, the published ports answer on the server address from other machines, but not on localhost from the server itself.

    Back up the data and shared folders of the kit directory.

    Why Core Hub reads its configuration from C:\gsconfig

    The Core Hub image declares C:\opt\gluesync\data and C:\opt\gluesync\shared as volumes, and Windows refuses a Swarm mount onto those paths (hcs::CreateComputeSystem …​ The request is not supported). The stack therefore mounts the kit’s shared and data\core-hub folders under C:\gsconfig, and tells Core Hub so with COMMONS_CONFIG_DIR, DATA_DIR and LOG_CONFIG_FILE. The kit’s shared\security-config.json points the TLS keystore to C:\gsconfig as well.

    Keep the C:\gsconfig mounts and these settings when you edit docker-stack.yml.

    The Windows stack also sets two Conductor settings: DOCKER_CLI_PATH points to the Docker CLI in the Windows image, and UPDATE_VERIFY_MAX_WAIT_SECONDS is 600, because a Windows image is a few gigabytes.

    Edit the stack

    The kit’s docker-stack.yml is the source of truth for the stack. After you edit it, run ./deploy.sh (Linux) or .\deploy.ps1 (Windows) again.

    • Image fields: keep them as literal repo:tag values. Conductor rewrites the image: line of a service when it updates it, and leaves an image written with a variable, such as ${VAR}, alone.

    • Resources: the stack sets no CPU or memory limits, because Swarm rejects a limit above a node’s CPU count. Add deploy.resources to the services to match your nodes.

    • Environment: docker stack deploy does not read .env on its own. The deploy scripts and Conductor load it before they deploy.

    docker stack rm gluesync removes every service of the stack. The data in the bind-mounted folders stays, but Gluesync stops until you deploy again.

    Conductor in Swarm mode

    Conductor recognizes a Swarm stack from the labels of its own service; the kit also sets CONDUCTOR_ORCHESTRATOR=swarm. The Conductor API is the same in both modes, so Platform updates and the other Core Hub pages work as with Docker Compose.

    Conductor must run on a Swarm manager, because only managers answer the Swarm API for services, tasks and service logs. On a worker, Conductor answers every request with the diagnosis code SWARM_NOT_MANAGER. The kit places it on the manager labelled gluesync.kit=true, with the Docker socket (Linux) or named pipe (Windows) and the kit directory mounted.

    Updates with automatic rollback

    When you update a service from Platform updates, Conductor:

    1. Leaves a service that already runs the image of the stack file untouched.

    2. Sets the new image on the service, with automatic rollback as the failure action.

    3. Waits until the update has completed and all replicas have kept running for UPDATE_VERIFY_SECONDS (default 20). It waits at most UPDATE_VERIFY_MAX_WAIT_SECONDS (default 180).

    4. Writes the new tag to docker-stack.yml, so that a later deploy does not revert the update.

    If the new version does not become stable, Swarm rolls the service back to its previous image, or Conductor rolls it back when Swarm has not. The update is reported as failed and the stack file keeps the previous tag.

    Swarm pulls the new image while it starts the new task. The time spent downloading does not count against UPDATE_VERIFY_MAX_WAIT_SECONDS, so a large image is not rolled back for downloading slowly. UPDATE_PULL_MAX_WAIT_SECONDS (default 1200) limits the download itself.

    When Conductor updates itself, it replies to the request first and then updates its own service. If the new Conductor fails to start, Swarm rolls it back, and the Conductor that starts again writes its own image back to the stack file.

    Release channel switch

    Conductor in Swarm mode updates itself only to a newer version. Older Conductor releases do not support Swarm, and installing one would break the stack.

    • An alpha build of a version updates to the beta or GA release of the same version, or to a later one. You can therefore switch the release channel in Platform updates from alpha to beta or GA without losing Swarm support.

    • Conductor never updates itself to an older version, for example when the GA channel still offers a release without Swarm support.

    When the target version is refused, the Conductor entry of the update reports the reason and Conductor is not offered as an update; the other services are updated as usual.

    No restart on redeploy

    After an update, Conductor pins the service to the digest of the new image and gives the service its own update settings back, also when the update was rolled back. Running ./deploy.sh or .\deploy.ps1 again afterwards therefore does not restart the services that Conductor updated.

    Other differences from Docker Compose

    Action In Swarm mode

    Start

    Scales the service to the replicas of the stack file (default 1). A service that does not exist yet is created with docker stack deploy.

    Stop

    Scales the service to 0 replicas.

    Restart

    Forces a rolling update of the service and waits until it has converged. Restarting the whole stack restarts Conductor last.

    Pull

    Does nothing: Swarm pulls the image during the update.

    Collect logs

    Reads the logs with docker service logs, so it includes the tasks on every node.

    Migration to Gluesync 2.x

    Not supported. Conductor refuses it with the diagnosis code SWARM_UNSUPPORTED.

    In Swarm mode, Conductor does not edit the stack file or recreate services at startup, as it does to heal a Docker Compose installation, and it does not prune old images after an update, because the Docker API only reaches the manager.

    For the settings that tune these behaviours, see the environment configuration of Gluesync Conductor.

    Next steps

    For Swarm concepts and commands, see the Docker Swarm documentation and the docker stack deploy reference.