Skip to content
The Chat Archive
gemini-2.5-flash-lite-preview-06-17-thinking· Google LMArena Human Preference 140K

instructions on setting up docker swarm with portainer

  1. User

    instructions on setting up docker swarm with portainer

  2. Assistant

    Okay, here are the step-by-step instructions to set up a Docker Swarm cluster and deploy Portainer (Community Edition) onto it.

    Goal: Create a Docker Swarm cluster with at least one manager and one worker node, then deploy Portainer using a Docker Stack file.

    Prerequisites:

    1. Machines: At least two machines (physical or virtual) that can communicate with each other over the network. Let's call them manager-node and worker-node-1. You can add more worker nodes later.
    2. Docker Engine: Docker must be installed and running on all nodes. Ensure you are using compatible versions. Check with docker --version.
    3. SSH Access: You need SSH access to all nodes, preferably from the machine where you'll run the initial commands, or directly on the manager node.
    4. Network Connectivity: Nodes must be able to reach each other. Ensure firewalls (if any) allow communication on necessary Docker ports (TCP 2377 for Swarm management, TCP/UDP 7777 and 7778 for overlay network communication - though these can vary, 2377 is key). Portainer UI will typically use 9443 (HTTPS).
    5. IP Addresses: Know the private IP addresses of your nodes.

    Step 1: Prepare the Nodes

    1. Install Docker: Ensure Docker Engine is installed and the Docker service is running on all nodes (manager-node, worker-node-1, etc.). Follow the official Docker installation guide for your specific OS if needed.
      • Check status: sudo systemctl status docker
      • Start if needed: sudo systemctl start docker
      • Enable on boot: sudo systemctl enable docker
    2. SSH: Ensure you can SSH into each node. It's often easiest to perform the Swarm setup steps directly on the intended manager node via SSH.

    Step 2: Initialize Docker Swarm on the Manager Node

    1. SSH into manager-node.
    2. Initialize Swarm: Run the following command, replacing <MANAGER_IP> with the actual IP address of this manager-node. This IP is how other nodes will reach the manager.
      sudo docker swarm init --advertise-addr <MANAGER_IP>
      
      Example:
      sudo docker swarm init --advertise-addr 192.168.1.100
      
    3. Note the Output: The command will output information about the Swarm and, crucially, a docker swarm join command with a join token for worker nodes. It will look something like this:
      Swarm initialized: current node (...) is now a manager.
      
      To add a worker to this swarm, run the following command:
      
          docker swarm join --token SWMTKN-1-XXXXXXXXXXXXXX <MANAGER_IP>:2377
      
      To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
      
      Copy and save this worker join command securely.

    Step 3: Join Worker Nodes to the Swarm

    1. SSH into worker-node-1 (and any other worker nodes you want to add).
    2. Run the Join Command: Paste and run the docker swarm join command you saved from Step 2, ensuring you are doing this on the worker node.
      # Example command - replace token and IP!
      sudo docker swarm join --token SWMTKN-1-XXXXXXXXXXXXXX <MANAGER_IP>:2377
      
      Example:
      sudo docker swarm join --token SWMTKN-1-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7 <192.168.1.100>:2377
      
    3. Repeat this step for any additional worker nodes. The node should confirm it has joined the Swarm.

    Step 4: Verify Swarm Status

    1. Go back to the manager-node (via SSH).
    2. List Nodes: Run the following command to see all nodes in the Swarm:
      sudo docker node ls
      
    3. Check Output: You should see your manager-node listed with * next to it, marked as Leader, and your worker-node-1 (and others) listed with the status Ready and role worker.

    Step 5: Deploy Portainer using a Docker Stack File

    1. Create a Stack File: On your manager-node, create a file named portainer-stack.yml (or any name you prefer, like docker-compose.yml).

    2. Add Portainer Configuration: Paste the following content into the file.

      version: "3.7"
      
      services:
        ## Portainer Agent Service (runs on every node)
        agent:
          image: portainer/agent:latest
          deploy:
            mode: global # Ensures the agent runs on every node in the swarm
            restart_policy:
              condition: on-failure
          volumes:
            - /var/run/docker.sock:/var/run/docker.sock # Mount docker socket for agent communication
          # Optional: Define placement constraints if needed, but 'global' usually suffices
          # placement:
          #  constraints:
          #    - node.platform.os == linux
      
        ## Portainer UI Service (runs as a replicated service, typically on manager)
        portainer:
          image: portainer/portainer-ce:latest # Use Community Edition
          command: -H tcp://tasks.agent:9001 # Connects to the agent via internal DNS
          ports:
            - "9443:9443" # Expose HTTPS port to the host
            # Optional: Expose HTTP port if needed (less secure)
            # - "9000:9000"
          volumes:
            - portainer_data:/data # Use a named volume for persistent data
          deploy:
            mode: replicated # Run as a replicated service
            replicas: 1 # Only one instance of the UI is needed
            placement:
              constraints:
                - node.role == manager # Recommended: Run UI on manager node(s)
          depends_on:
            - agent # Ensures agent starts before portainer UI (helps with initial DNS resolution)
      
      volumes:
        portainer_data: # Define the named volume for Portainer data
      

      Explanation:

      • agent service: Uses the portainer/agent image. mode: global ensures it runs on every node. It needs access to the host's Docker socket (/var/run/docker.sock).
      • portainer service: Uses the portainer/portainer-ce image. mode: replicated with replicas: 1 means only one instance runs. We constrain it to run on a manager node. It exposes port 9443 (HTTPS) and uses a named volume portainer_data for persistence. It connects to the agents via the internal Swarm service discovery (tasks.agent:9001).
    3. Deploy the Stack: Run the following command on the manager-node:

      sudo docker stack deploy -c portainer-stack.yml portainer
      
      • -c portainer-stack.yml: Specifies the stack definition file.
      • portainer: Is the name given to this stack.

    Step 6: Access Portainer UI

    1. Wait: Give it a minute or two for the containers to pull and start.
    2. Check Status (Optional): You can check the status of the services:
      sudo docker stack ps portainer
      sudo docker service ls
      
    3. Open Browser: Navigate to https://<MANAGER_IP>:9443 in your web browser (use the IP address of your manager-node and the port 9443).
    4. Login: You'll be prompted to create an administrator username and password for Portainer. Create a strong password.
    5. Endpoint: Portainer should automatically detect your Docker Swarm environment. If prompted to select an endpoint, choose the default one representing your Swarm.

    Congratulations! You now have Portainer running on your Docker Swarm cluster. You can manage your Swarm services, nodes, volumes, and networks through the Portainer web interface.

    Next Steps & Considerations:

    • Add More Nodes: Repeat Step 3 to add more worker nodes to your Swarm.
    • Add More Managers: For high availability, you can promote existing nodes or add new ones as managers using docker swarm join-token manager on the manager node and then running the join command on the new manager node. Then use sudo docker node promote <node_id> on an existing manager.
    • Security:
      • Always use HTTPS (port 9443).
      • Use strong passwords for Portainer.
      • Consider restricting access to the Portainer UI port (9443) using firewall rules.
      • Secure the Docker daemon socket access.
    • Backup: Regularly back up the portainer_data volume on your manager node. You can inspect the volume (sudo docker volume inspect portainer_data) to find its mount point on the host or use Docker volume backup tools/methods.

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.