How to Scaling Docker Swarm with Komodo Platform

Scaling your infrastructure is crucial for any growing operation, and Komodo offers a robust solution for managing multiple servers. This guide walks you through the process of seamlessly integrating additional servers into your Komodo ecosystem, enhancing its capabilities and efficiency. We'll cover both the installation of the Periphery agent and its configuration, ensuring a secure and streamlined setup.

Connecting a server to Komodo is a two-step process: deploying the Periphery agent and then registering that server with the Komodo Core. Let's dive into the details.

Deploying the Periphery Agent: Your Gateway to Multi-Server Management

The Periphery agent acts as the bridge between your individual servers and the Komodo Core. You have several options for installing the Periphery agent, each offering flexibility based on your server environment.

Systemd Installation: The Reliable Approach

For a robust and reliable installation managed by your system's init system, use the systemd installation script. This method ensures that the Periphery agent starts automatically with the server and benefits from systemd's process management capabilities.

The following commands facilitate a streamlined installation, adapting to your user privileges:

# For root installation
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | python3

# For installation as the current user (requires additional configuration)
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | python3 - --user
    

This script is idempotent; running it multiple times won't cause issues. Simply rerun it after Komodo version updates to ensure you have the latest Periphery version. The script handles the complexities of installation and configuration, ensuring a smooth setup.

Docker Containerization: Portability and Isolation

For enhanced portability and isolation, containerizing the Periphery agent using Docker is a preferred approach. This method provides a consistent environment across different server platforms, minimizing potential compatibility issues.

The following docker-compose configuration file provides a comprehensive example:

version: "3.9"
services:
  periphery:
    image: ghcr.io/mbecker20/periphery:latest
    # image: ghcr.io/mbecker20/periphery:latest-aarch64 # Use for ARM support
    labels:
      komodo.skip: # Prevents Komodo from attempting to stop the container with StopAllContainers
    logging:
      driver: local
    ports:
      - 8120:8120 # Exposes port 8120 for communication
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Mounts the Docker socket for container interaction
      - /proc:/proc # Allows Periphery to access host processes
      - ssl-certs:/etc/komodo/ssl # Mounts SSL certificates (use self-signed or your own)
      - repos:/etc/komodo/repos # Mounts repository directory (adjust path as needed)
      - stacks:/etc/komodo/stacks # Mounts stack directory (adjust path as needed)
      # - /path/to/compose:/host/compose # Optional: Mount path for compose files
    environment:
      # Full config options available at: https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml
      PERIPHERY_PASSKEYS: your_core_passkey # Your Komodo Core passkey (alternatively use PERIPHERY_PASSKEYS_FILE)
      PERIPHERY_ALLOWED_IPS: # Optional: Restrict access by IP address
      PERIPHERY_SSL_ENABLED: true # Enables HTTPS
      PERIPHERY_INCLUDE_DISK_MOUNTS: /etc/hostname # Optional: Whitelist disk mounts for accurate reporting (comma-separated list)
      # PERIPHERY_EXCLUDE_DISK_MOUNTS: /snap,/etc/repos # Optional: Blacklist disk mounts
volumes:
  ssl-certs:
  repos:
  stacks:
    

Remember to replace "your_core_passkey" with the actual passkey from your Komodo Core configuration. Carefully consider the volume mounts; adjusting paths as necessary to reflect your server's directory structure.

Manual Binary Installation: A Customized Approach

For users preferring direct control, a manual binary installation allows for a highly customized setup.

1. Download the Periphery binary from the latest release.

2. Create and configure your Periphery configuration file (periphery.config.toml), referencing the example configuration provided later in this guide.

3. Ensure inbound connectivity is allowed on the port specified in your configuration file (default is 8120). Firewall adjustments may be necessary.

4. If using Docker, ensure the user running Periphery has access to the docker group without requiring sudo.

5. Start the Periphery binary using your preferred process manager (like systemd).

An example command to start Periphery, demonstrating the flexibility of config file management:

periphery \
    --config-path /path/to/periphery.config.base.toml \
    --config-path /other_path/to/overide-periphery-config-directory \
    --config-keyword periphery \
    --config-keyword config \
    --merge-nested-config true
    

This example shows how multiple configuration files can be merged, with later files overriding earlier ones. The --merge-nested-config true option enables recursive merging, allowing for granular control over configuration settings. Consult the Periphery documentation for more advanced usage.

Security Considerations: Protecting Your Komodo Deployment

Security is paramount. Unrestricted access to the Periphery agent API poses a significant risk. Implement the following security measures:

• Firewall Rules: Restrict access to port 8120 (or your chosen port) using firewall rules to only allow trusted IP addresses.

• Whitelist IPs: In your Periphery configuration, specify allowed IP addresses to further limit access.

• Passkey Authentication: Use passkeys to authenticate requests from the Komodo Core, preventing unauthorized access. This significantly enhances the security posture of your Komodo setup.

Configuration: Fine-Tuning Your Periphery Agent

The Periphery configuration file (periphery.config.toml) allows for granular control over the agent's behavior. You can download a sample configuration file using the command:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/periphery.config.toml
    

This file provides detailed comments explaining each configuration option, including defaults and environment variable overrides. Pay close attention to the authentication section (passkeys and allowed IPs), the logging settings, and the various settings for managing repositories, stacks, and secrets. Customize this file to fit your specific environment and security requirements.

Registering the Server with Komodo Core: Completing the Connection

Once the Periphery agent is successfully installed and configured, the final step is to register the server with the Komodo Core. This typically involves using the Komodo Core API or UI. The specific steps may vary slightly depending on your Komodo version, but generally, it involves providing the Periphery agent's address and credentials. Consult the Komodo documentation for detailed instructions on server registration.

By following these steps and implementing the necessary security measures, you can efficiently integrate multiple servers into your Komodo environment, unlocking a world of possibilities for scaling and managing your infrastructure.