Ansible collection: ahmz1833.server_setup

Roles for Debian/Ubuntu-style hosts: base hardening, edge Nginx (optional ModSecurity), TLS automation, Docker workloads, and optional SSH-into-container sandboxes. Binaries and static bundles are installed through a shared asset role used internally by node, nginx, and acme.

Galaxy namespace: ahmz1833 · Collection name: server_setup · FQCN prefix: ahmz1833.server_setup.<role>

---

Requirements

Requirement	Notes
Ansible	2.14+ (ansible-core compatible)
Python	3.9+ on the controller
Targets	Roles are written for systemd-based Linux; several roles assume Debian/Ubuntu packages or paths—see each role README.

Collection dependencies

Declared in galaxy.yml; install with the collection or via ansible-galaxy collection install -r requirements.yml:

Collection	Purpose (examples)
community.general	archive, and other helpers
community.crypto	TLS / crypto (e.g. ACME)
community.docker	docker_container, docker_network, …
ansible.posix	sysctl, authorized_key, …
ansible.utils	IP / text utilities where used

---

Installation

From Ansible Galaxy (after publish)

ansible-galaxy collection install ahmz1833.server_setup

Pin a version:

ansible-galaxy collection install ahmz1833.server_setup:==1.0.0

From Git

requirements.yml:

---
collections:
  - name: https://github.com/ahmz1833/server-setup.git
    type: git
    version: master

ansible-galaxy collection install -r requirements.yml

Use your repository’s default branch (main, master, or a tag) for version.

Build and install from a checkout

cd /path/to/server-setup
ansible-galaxy collection build
ansible-galaxy collection install ahmz1833-server_setup-1.0.0.tar.gz

The artifact name is {namespace}-{name}-{version}.tar.gz.

Publishing to Galaxy (maintainers)

1. Bump version in galaxy.yml (semantic versioning).
2. ansible-galaxy collection build
3. ansible-galaxy collection publish ahmz1833-server_setup-<version>.tar.gz --token <GALAXY_API_TOKEN>

Ensure the namespace in galaxy.yml matches your Galaxy namespace (ahmz1833).

GitHub Actions now automates this flow:

• Pull requests and pushes to master run linting plus a build/install smoke test.
• Tag pushes publish to Galaxy after verifying the tag matches the galaxy.yml version.
• Set the repository secret GALAXY_API_TOKEN for publishing.

---

Roles overview

Role	Purpose
ahmz1833.server_setup.core	Timezone, APT mirrors, packages, users, SSH hardening, iptables/nftables-style firewall, sysctl, fail2ban.
ahmz1833.server_setup.node	Sing-box, GOST, X-UI, Docker (static engine + plugins), shell tools, node_exporter; uses asset for downloads.
ahmz1833.server_setup.nginx	Debian Nginx, ModSecurity CRS, vhosts from nginx_sites, exporter/Promtail optional; depends on asset.
ahmz1833.server_setup.acme	DNS-01 / HTTP-01 certificates; uses asset where applicable.
ahmz1833.server_setup.apps	Declarative docker_container stacks: deps, health wait, preserve mode, optional prune.
ahmz1833.server_setup.sandbox	SSH on a dedicated port into per-user Docker sandboxes (blockinfile on sshd_config).
ahmz1833.server_setup.k3s	Composable, property-driven K3s cluster provisioning, Day 0/1/2 lifecycle, firewall isolation, and host Nginx coexistence.
ahmz1833.server_setup.mail	Docker-based mail server (DKIM/DMARC/SPF), SSoT user management, and SnappyMail.
ahmz1833.server_setup.asset	Generic download / extract / install helper (binaries, files, packages); dependency of other roles.

Each role has its own roles/<name>/README.md for variables and examples.

---

Quick examples

Core

- hosts: all
  become: true
  roles:
    - role: ahmz1833.server_setup.core
      vars:
        is_iran: false
        core_manage_users: true
        core_manage_ssh: true
        core_manage_firewall: true

Node

- hosts: all
  become: true
  roles:
    - role: ahmz1833.server_setup.node
      vars:
        node_docker_enabled: true
        node_gost_enabled: true
        node_exporter_enabled: true

Nginx

- hosts: edge
  become: true
  roles:
    - role: ahmz1833.server_setup.nginx
      vars:
        nginx_managed: true
        nginx_sites:
          - domain: example.com
            ssl_enabled: true
            upstream: "http://127.0.0.1:8080"

ACME

- hosts: all
  become: true
  roles:
    - role: ahmz1833.server_setup.acme
      vars:
        acme_account_email: admin@example.com
        acme_certificates:
          - domains:
              - example.com
              - "*.example.com"

Apps (apps_list)

- hosts: app_servers
  become: true
  roles:
    - role: ahmz1833.server_setup.apps
      vars:
        apps_list:
          - name: web
            image: nginx:alpine
            ports:
              - "8080:80"

Sandbox

- hosts: all
  become: true
  roles:
    - role: ahmz1833.server_setup.sandbox
      vars:
        sandbox_ssh_port: 2222
        sandbox_users:
          - name: guest1
            ssh_keys:
              - "ssh-ed25519 AAAA... your-key"
            image: ubuntu:24.04

Connect as sandbox@host (or your sandbox_shared_user) on sandbox_ssh_port; see the sandbox role README.

Mail

- hosts: mail_servers
  become: true
  roles:
    - role: ahmz1833.server_setup.mail
      vars:
        mail_domain: "example.com"
        mail_hostname: "mail.example.com"
        mail_admin_username: "admin"
        mail_admin_password: "SuperSecretPassword123"

K3s

- hosts: k3s_servers:k3s_agents
  become: true
  roles:
    - role: ahmz1833.server_setup.core
    - role: ahmz1833.server_setup.k3s
      vars:
        k3s_state: present

---

Cross-role playbook variables

Set at play, group, or host level when you want shared behavior:

Variable	Typical use
is_iran	core: timezone/mirrors; node: node_internet_restricted; nginx: nginx_download_locally (via default expression).
enable_ipv6	core: sysctl/firewall IPv6; nginx: listen [::]:… when enabled.
primary_user	core: core_primary_user (protected user, SSH keys).
download_locally	node: fetch artifacts on the controller / cache (node_download_locally); also referenced by roles that pass it into asset.

Exact wiring is in each role’s defaults/main.yml.

---

Repository layout

• galaxy.yml — collection metadata for ansible-galaxy collection build / publish.
• roles/ — one directory per role (core, node, nginx, acme, apps, sandbox, asset).
• playbooks/ — optional sample playbooks (not required to use the collection).

---

License

MIT