This handbook uses consistent formatting and terminology to improve readability and reduce ambiguity.

Command Line Conventions

Shell Commands:

# Commands to be executed as regular user
docker service ls

# Commands requiring root privileges
sudo systemctl restart docker

# Commands with placeholder values
docker service update --image new-image:TAG service-name

Command Output:

# Expected output is shown in code blocks
ID             NAME              MODE         REPLICAS   IMAGE
abc123def456   example_service   replicated   1/1        nginx:latest

Multi-line Commands:

# Line continuation with backslash
docker service create \
  --name web-service \
  --replicas 3 \
  nginx:latest

File and Directory Conventions

File Paths:

  • Absolute paths:/mnt/swarm-data/service/config.yml
  • Relative paths:config/service.yml
  • Variables in paths:/mnt/swarm-data/SERVICE-NAME/data

File Content Examples:

# Complete YAML files shown with syntax highlighting
services:
  example:
    image: nginx:latest
    ports:
      - "80:80"

Configuration Snippets:

# Partial configuration files shown with context
# /etc/docker/daemon.json
{
  "mtu": 1450
}

Naming Conventions

Services and Stacks:

  • Stack names:auth,nextcloud,paperless
  • Service names:auth_authentik_server,nextcloud_nextcloud
  • Container names: Generated automatically by Docker Swarm

Network and Volume Names:

  • Networks:homelab,portainer_portainer_agent
  • Volumes:auth_authentik_media,postgresql17_master_db_data

Node References:

  • Manager node:p0(Beelink SER5)
  • Worker nodes:p1,p2,p3(Raspberry Pi 5)

Security and Sensitive Information

Credential Handling:

  • Sensitive values marked as[SECRET]
  • Environment variables shown without actual values
  • Example credentials clearly labeled as non-functional

Security Notes:

Security Note: Important security considerations highlighted in block quotes

Warning Indicators:

Warning: Critical information that could cause data loss or security issues

Code and Configuration Standards

YAML Formatting:

  • 2-space indentation
  • Consistent key ordering within sections
  • Comments explaining non-obvious configuration

Variable Placeholders:

  • SERVICE-NAME: Replace with actual service name
  • [SECRET]: Replace with actual credential
  • node-name: Replace with actual hostname

Cross-References

Internal References:

  • Chapter references: “See Chapter 3: Storage and Persistence”
  • Section references: “As described in Section 5.2”
  • Command references: “Use the backup script from Section 6.2”

External References:

  • Documentation links provided for third-party tools
  • Version-specific information noted where applicable
  • Official documentation preferred over unofficial sources

This handbook maintains these conventions throughout to ensure consistent interpretation and successful implementation of the documented procedures.