Add Template to deploy forgejo.

This template allows deploying a forgejo en either Scaleway or Hetzner
(untested) without much knowledge about them.
It DOES require knowledge about Terragrunt and ansible. A wizard of
sorts is provided but it will not guarantee success without some
knowledge about the underlying technology.

ansible/roles/forgejo/tasks/backup.yml

@@ -0,0 +1,32 @@
+---
+# Backup configuration tasks
+
+- name: Create backup script
+  ansible.builtin.template:
+    src: forgejo_backup.sh.j2
+    dest: /usr/local/bin/forgejo_backup.sh
+    mode: '0755'
+  become: yes
+
+- name: Set up backup cron job
+  ansible.builtin.cron:
+    name: "Forgejo daily backup"
+    minute: "{{ forgejo_backup_schedule.split()[0] }}"
+    hour: "{{ forgejo_backup_schedule.split()[1] }}"
+    job: "/usr/local/bin/forgejo_backup.sh >> /var/log/forgejo-backup.log 2>&1"
+  become: yes
+
+- name: Create log rotation for backup logs
+  ansible.builtin.copy:
+    dest: /etc/logrotate.d/forgejo-backup
+    content: |
+      /var/log/forgejo-backup.log {
+          daily
+          rotate 7
+          compress
+          delaycompress
+          missingok
+          notifempty
+      }
+    mode: '0644'
+  become: yes

ansible/roles/forgejo/tasks/caddy.yml

@@ -0,0 +1,71 @@
+---
+# Caddy web server setup tasks
+# Caddy handles HTTPS certificates automatically via Let's Encrypt
+
+- name: Install dependencies for Caddy
+  ansible.builtin.apt:
+    name:
+      - debian-keyring
+      - debian-archive-keyring
+      - apt-transport-https
+      - curl
+    state: present
+    update_cache: yes
+  become: yes
+
+- name: Add Caddy GPG key
+  ansible.builtin.shell: |
+    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+  args:
+    creates: /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+  become: yes
+
+- name: Add Caddy repository
+  ansible.builtin.shell: |
+    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
+  args:
+    creates: /etc/apt/sources.list.d/caddy-stable.list
+  become: yes
+
+- name: Install Caddy
+  ansible.builtin.apt:
+    name: caddy
+    state: present
+    update_cache: yes
+  become: yes
+
+- name: Create Caddy configuration directory
+  ansible.builtin.file:
+    path: /etc/caddy
+    state: directory
+    owner: root
+    group: root
+    mode: '0755'
+  become: yes
+
+- name: Create Caddy log directory
+  ansible.builtin.file:
+    path: /var/log/caddy
+    state: directory
+    owner: caddy
+    group: caddy
+    mode: '0755'
+  become: yes
+
+- name: Create Caddyfile for Forgejo
+  ansible.builtin.template:
+    src: Caddyfile.j2
+    dest: /etc/caddy/Caddyfile
+    owner: root
+    group: root
+    mode: '0644'
+    validate: 'caddy validate --adapter caddyfile --config %s'
+  become: yes
+  notify: Reload Caddy
+
+- name: Ensure Caddy is started and enabled
+  ansible.builtin.systemd:
+    name: caddy
+    state: started
+    enabled: yes
+  become: yes

ansible/roles/forgejo/tasks/docker.yml

@@ -0,0 +1,100 @@
+---
+# Docker installation tasks
+
+- name: Check if Docker is already installed
+  ansible.builtin.command: docker --version
+  register: docker_installed
+  changed_when: false
+  failed_when: false
+
+- name: Install Docker
+  when: docker_installed.rc != 0
+  block:
+    - name: Install Docker dependencies
+      ansible.builtin.apt:
+        name:
+          - apt-transport-https
+          - ca-certificates
+          - curl
+          - gnupg
+          - lsb-release
+        state: present
+        update_cache: yes
+      become: yes
+
+    - name: Create directory for Docker GPG key
+      ansible.builtin.file:
+        path: /etc/apt/keyrings
+        state: directory
+        mode: '0755'
+      become: yes
+
+    - name: Add Docker GPG key
+      ansible.builtin.apt_key:
+        url: https://download.docker.com/linux/ubuntu/gpg
+        keyring: /etc/apt/keyrings/docker.gpg
+        state: present
+      become: yes
+
+    - name: Add Docker repository
+      ansible.builtin.apt_repository:
+        repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu {{ ansible_distribution_release }} stable"
+        state: present
+        filename: docker
+      become: yes
+
+    - name: Install Docker Engine
+      ansible.builtin.apt:
+        name:
+          - docker-ce
+          - docker-ce-cli
+          - containerd.io
+          - docker-buildx-plugin
+          - docker-compose-plugin
+        state: present
+        update_cache: yes
+      become: yes
+
+- name: Add Forgejo user to Docker group
+  ansible.builtin.user:
+    name: "{{ forgejo_user }}"
+    groups: docker
+    append: yes
+  become: yes
+
+- name: Ensure Docker service is started and enabled
+  ansible.builtin.systemd:
+    name: docker
+    state: started
+    enabled: yes
+    daemon_reload: yes
+  become: yes
+
+- name: Configure Docker daemon
+  ansible.builtin.copy:
+    dest: /etc/docker/daemon.json
+    content: |
+      {
+        "log-driver": "json-file",
+        "log-opts": {
+          "max-size": "10m",
+          "max-file": "3"
+        },
+        "storage-driver": "overlay2",
+        "userland-proxy": false,
+        "live-restore": true
+      }
+    mode: '0644'
+  become: yes
+  notify: Restart Docker
+
+- name: Verify Docker installation
+  ansible.builtin.command: docker run --rm hello-world
+  register: docker_test
+  changed_when: false
+  become: yes
+
+- name: Display Docker version
+  ansible.builtin.debug:
+    msg: "Docker is installed and working"
+  when: docker_test.rc == 0

ansible/roles/forgejo/tasks/forgejo.yml

@@ -0,0 +1,138 @@
+---
+# Forgejo deployment tasks
+
+- name: Ensure Forgejo data directories have correct ownership
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+    owner: "{{ forgejo_uid }}"
+    group: "{{ forgejo_gid }}"
+    mode: '0755'
+    recurse: yes
+  become: yes
+  loop:
+    - "{{ forgejo_data_path }}"
+    - "{{ forgejo_config_path }}"
+    - "{{ forgejo_custom_path }}"
+
+- name: Create .ssh directory for Forgejo
+  ansible.builtin.file:
+    path: "{{ forgejo_data_path }}/git/.ssh"
+    state: directory
+    owner: "{{ forgejo_uid }}"
+    group: "{{ forgejo_gid }}"
+    mode: '0700'
+  become: yes
+
+- name: Create Forgejo configuration from template
+  ansible.builtin.template:
+    src: app.ini.j2
+    dest: "{{ forgejo_config_path }}/app.ini"
+    owner: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    mode: '0640'
+  become: yes
+  notify: Restart Forgejo
+
+- name: Create Docker Compose file
+  ansible.builtin.template:
+    src: docker-compose.yml.j2
+    dest: "{{ forgejo_base_path }}/docker-compose.yml"
+    owner: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    mode: '0640'
+  become: yes
+  notify: Restart Forgejo
+
+- name: Pull Forgejo Docker image
+  community.docker.docker_image:
+    name: "{{ forgejo_docker_image }}:{{ forgejo_version }}"
+    source: pull
+  become: yes
+
+- name: Start Forgejo with Docker Compose
+  community.docker.docker_compose_v2:
+    project_src: "{{ forgejo_base_path }}"
+    state: present
+  become: yes
+  register: forgejo_started
+
+- name: Wait for Forgejo to be ready
+  ansible.builtin.uri:
+    url: "http://localhost:{{ forgejo_http_port }}"
+    status_code: 200
+  register: forgejo_health
+  until: forgejo_health.status == 200
+  retries: 30
+  delay: 5
+  ignore_errors: yes
+
+- name: Get Forgejo container logs if startup failed
+  ansible.builtin.command:
+    cmd: docker logs forgejo --tail 50
+  register: forgejo_logs
+  become: yes
+  when: forgejo_health.status is not defined or forgejo_health.status != 200
+
+- name: Show Forgejo container logs
+  ansible.builtin.debug:
+    var: forgejo_logs.stdout_lines
+  when: forgejo_logs is defined and forgejo_logs.stdout_lines is defined
+
+- name: Fail if Forgejo is not ready
+  ansible.builtin.fail:
+    msg: "Forgejo failed to start. Check logs above."
+  when: forgejo_health.status is not defined or forgejo_health.status != 200
+
+- name: Check if admin user exists
+  ansible.builtin.command:
+    cmd: docker exec --user git forgejo forgejo admin user list --admin
+  register: admin_user_check
+  become: yes
+  changed_when: false
+  failed_when: false
+
+- name: Create admin user
+  ansible.builtin.command:
+    cmd: >
+      docker exec --user git forgejo forgejo admin user create
+      --admin
+      --username "{{ forgejo_admin_username }}"
+      --password "{{ forgejo_admin_password }}"
+      --email "{{ forgejo_admin_email }}"
+      --must-change-password=false
+  become: yes
+  when: forgejo_admin_username not in admin_user_check.stdout
+  register: admin_created
+  no_log: yes
+
+- name: Display admin credentials
+  ansible.builtin.debug:
+    msg: |
+      =====================================================
+      ADMIN USER CREATED
+      =====================================================
+      Username: {{ forgejo_admin_username }}
+      Email:    {{ forgejo_admin_email }}
+      Password: (from your secrets.yml vault)
+
+      IMPORTANT: Change this password after first login!
+      =====================================================
+  when: admin_created is defined and admin_created.changed
+
+- name: Create Forgejo systemd service
+  ansible.builtin.template:
+    src: forgejo.service.j2
+    dest: /etc/systemd/system/forgejo.service
+    mode: '0644'
+  become: yes
+  notify:
+    - Reload Systemd
+    - Restart Forgejo
+
+- name: Enable Forgejo service
+  ansible.builtin.systemd:
+    name: forgejo
+    enabled: yes
+    daemon_reload: yes
+  become: yes

ansible/roles/forgejo/tasks/main.yml

@@ -0,0 +1,94 @@
+---
+# Main tasks for Forgejo deployment
+
+- name: Include system preparation tasks
+  ansible.builtin.include_tasks: prepare.yml
+  tags:
+    - prepare
+    - system
+
+- name: Include Tailscale VPN setup tasks
+  ansible.builtin.include_tasks: tailscale.yml
+  when: forgejo_enable_tailscale | bool
+  tags:
+    - tailscale
+    - security
+    - vpn
+
+- name: Include volume setup tasks
+  ansible.builtin.include_tasks: volume.yml
+  when: forgejo_use_external_volume | bool
+  tags:
+    - volume
+    - storage
+
+- name: Include Docker installation tasks
+  ansible.builtin.include_tasks: docker.yml
+  tags:
+    - docker
+    - install
+
+- name: Include PostgreSQL setup tasks
+  ansible.builtin.include_tasks: postgres.yml
+  when: forgejo_db_type == 'postgres'
+  tags:
+    - postgres
+    - database
+
+- name: Include Redis setup tasks
+  ansible.builtin.include_tasks: redis.yml
+  when: forgejo_use_redis | bool
+  tags:
+    - redis
+    - cache
+
+# Ensure PostgreSQL is restarted with new config before Forgejo connects
+- name: Flush handlers before starting Forgejo
+  ansible.builtin.meta: flush_handlers
+
+- name: Include Forgejo configuration tasks
+  ansible.builtin.include_tasks: forgejo.yml
+  tags:
+    - forgejo
+    - config
+
+- name: Include Caddy setup tasks
+  ansible.builtin.include_tasks: caddy.yml
+  tags:
+    - caddy
+    - webserver
+
+- name: Include SSL certificate tasks
+  ansible.builtin.include_tasks: ssl.yml
+  when: forgejo_enable_letsencrypt | bool
+  tags:
+    - ssl
+    - certificates
+
+- name: Include backup configuration tasks
+  ansible.builtin.include_tasks: backup.yml
+  when: forgejo_enable_backups | bool
+  tags:
+    - backup
+
+- name: Include restore tasks
+  ansible.builtin.include_tasks: restore.yml
+  when: forgejo_restore_from_backup | bool
+  tags:
+    - restore
+    - never  # Only run when explicitly requested
+
+- name: Include monitoring setup tasks
+  ansible.builtin.include_tasks: monitoring.yml
+  when: forgejo_enable_prometheus | bool
+  tags:
+    - monitoring
+    - prometheus
+
+- name: Include UFW firewall configuration tasks
+  ansible.builtin.include_tasks: ufw.yml
+  when: forgejo_enable_ufw | bool
+  tags:
+    - ufw
+    - firewall
+    - security

ansible/roles/forgejo/tasks/monitoring.yml

@@ -0,0 +1,66 @@
+---
+# Prometheus monitoring setup for Forgejo
+# This is INTERNAL monitoring - metrics are only accessible locally or via authenticated endpoint
+
+- name: Create monitoring directory
+  ansible.builtin.file:
+    path: "{{ forgejo_base_path }}/monitoring"
+    state: directory
+    owner: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    mode: '0755'
+  become: yes
+
+- name: Create Prometheus configuration
+  ansible.builtin.template:
+    src: prometheus.yml.j2
+    dest: "{{ forgejo_base_path }}/monitoring/prometheus.yml"
+    owner: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    mode: '0644'
+  become: yes
+  notify: Restart Prometheus
+
+- name: Create Prometheus Docker Compose override
+  ansible.builtin.template:
+    src: docker-compose.monitoring.yml.j2
+    dest: "{{ forgejo_base_path }}/docker-compose.monitoring.yml"
+    owner: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    mode: '0644'
+  become: yes
+  notify: Restart Prometheus
+
+- name: Create Prometheus data directory
+  ansible.builtin.file:
+    path: "{{ forgejo_base_path }}/monitoring/data"
+    state: directory
+    owner: "65534"  # nobody user in Prometheus container
+    group: "65534"
+    mode: '0755'
+  become: yes
+
+- name: Start Prometheus container
+  community.docker.docker_compose_v2:
+    project_src: "{{ forgejo_base_path }}"
+    files:
+      - docker-compose.yml
+      - docker-compose.monitoring.yml
+    state: present
+  become: yes
+
+- name: Display monitoring access information
+  ansible.builtin.debug:
+    msg: |
+      Prometheus monitoring is now enabled!
+
+      Internal access (from server):
+        - Prometheus UI: http://localhost:9090
+        - Forgejo metrics: http://localhost:3000/metrics (requires token)
+
+      The metrics endpoint is protected by a token configured in your secrets.yml
+      (vault_forgejo_metrics_token). Use this token in the Authorization header
+      or as a query parameter: /metrics?token=YOUR_TOKEN
+
+      Prometheus scrapes Forgejo metrics every 15 seconds.
+      Data is retained for 15 days by default.

ansible/roles/forgejo/tasks/postgres.yml

@@ -0,0 +1,163 @@
+---
+# PostgreSQL setup tasks
+
+- name: Install PostgreSQL
+  ansible.builtin.apt:
+    name:
+      - "postgresql-{{ postgres_version }}"
+      - "postgresql-contrib-{{ postgres_version }}"
+      - python3-psycopg2
+    state: present
+    update_cache: yes
+  become: yes
+
+- name: Ensure PostgreSQL is started and enabled
+  ansible.builtin.systemd:
+    name: postgresql
+    state: started
+    enabled: yes
+  become: yes
+
+- name: Create PostgreSQL data directory
+  ansible.builtin.file:
+    path: "{{ postgres_data_dir }}"
+    state: directory
+    owner: postgres
+    group: postgres
+    mode: '0700'
+  become: yes
+  when: forgejo_use_external_volume | bool
+
+- name: Check if PostgreSQL database exists
+  ansible.builtin.command:
+    cmd: psql -U postgres -lqt
+  register: postgres_db_list
+  changed_when: false
+  become: yes
+  become_user: postgres
+
+- name: Create Forgejo PostgreSQL database
+  community.postgresql.postgresql_db:
+    name: "{{ forgejo_db_name }}"
+    encoding: UTF8
+    lc_collate: en_US.UTF-8
+    lc_ctype: en_US.UTF-8
+    template: template0
+    state: present
+  become: yes
+  become_user: postgres
+  when: forgejo_db_name not in postgres_db_list.stdout
+
+- name: Create Forgejo PostgreSQL user
+  community.postgresql.postgresql_user:
+    name: "{{ forgejo_db_user }}"
+    password: "{{ forgejo_db_password }}"
+    state: present
+  become: yes
+  become_user: postgres
+  no_log: yes
+
+- name: Grant database privileges to Forgejo user
+  community.postgresql.postgresql_privs:
+    database: "{{ forgejo_db_name }}"
+    roles: "{{ forgejo_db_user }}"
+    type: database
+    privs: ALL
+  become: yes
+  become_user: postgres
+
+- name: Grant schema privileges to Forgejo user
+  community.postgresql.postgresql_privs:
+    database: "{{ forgejo_db_name }}"
+    roles: "{{ forgejo_db_user }}"
+    type: schema
+    objs: public
+    privs: ALL
+  become: yes
+  become_user: postgres
+
+- name: Set Forgejo user as owner of public schema
+  community.postgresql.postgresql_owner:
+    db: "{{ forgejo_db_name }}"
+    new_owner: "{{ forgejo_db_user }}"
+    obj_name: public
+    obj_type: schema
+  become: yes
+  become_user: postgres
+
+- name: Configure PostgreSQL for optimal performance
+  ansible.builtin.lineinfile:
+    path: "/etc/postgresql/{{ postgres_version }}/main/postgresql.conf"
+    regexp: "{{ item.regexp }}"
+    line: "{{ item.line }}"
+    state: present
+  become: yes
+  loop:
+    - { regexp: '^max_connections', line: "max_connections = {{ postgres_max_connections }}" }
+    - { regexp: '^shared_buffers', line: "shared_buffers = {{ postgres_shared_buffers }}" }
+    - { regexp: '^effective_cache_size', line: "effective_cache_size = {{ postgres_effective_cache_size }}" }
+    - { regexp: '^maintenance_work_mem', line: "maintenance_work_mem = 128MB" }
+    - { regexp: '^checkpoint_completion_target', line: "checkpoint_completion_target = 0.9" }
+    - { regexp: '^wal_buffers', line: "wal_buffers = 16MB" }
+    - { regexp: '^default_statistics_target', line: "default_statistics_target = 100" }
+    - { regexp: '^random_page_cost', line: "random_page_cost = 1.1" }
+    - { regexp: '^effective_io_concurrency', line: "effective_io_concurrency = 200" }
+    - { regexp: '^work_mem', line: "work_mem = 8MB" }
+    - { regexp: '^min_wal_size', line: "min_wal_size = 1GB" }
+    - { regexp: '^max_wal_size', line: "max_wal_size = 4GB" }
+  notify: Restart PostgreSQL
+
+- name: Configure PostgreSQL to listen on all interfaces
+  ansible.builtin.lineinfile:
+    path: "/etc/postgresql/{{ postgres_version }}/main/postgresql.conf"
+    regexp: "^#?listen_addresses"
+    line: "listen_addresses = '*'"
+    state: present
+  become: yes
+  notify: Restart PostgreSQL
+
+- name: Configure PostgreSQL authentication
+  ansible.builtin.lineinfile:
+    path: "/etc/postgresql/{{ postgres_version }}/main/pg_hba.conf"
+    regexp: "{{ item.regexp }}"
+    line: "{{ item.line }}"
+    state: present
+  become: yes
+  loop:
+    - regexp: '^local\s+all\s+postgres'
+      line: 'local   all             postgres                                peer'
+    - regexp: '^local\s+all\s+all'
+      line: 'local   all             all                                     peer'
+    - regexp: '^host\s+all\s+all\s+127\.0\.0\.1'
+      line: 'host    all             all             127.0.0.1/32            scram-sha-256'
+    - regexp: '^host\s+all\s+all\s+::1'
+      line: 'host    all             all             ::1/128                 scram-sha-256'
+  notify: Restart PostgreSQL
+
+- name: Allow Docker network to connect to PostgreSQL
+  ansible.builtin.lineinfile:
+    path: "/etc/postgresql/{{ postgres_version }}/main/pg_hba.conf"
+    line: 'host    all             all             172.16.0.0/12           scram-sha-256'
+    insertafter: '^host\s+all\s+all\s+127'
+    state: present
+  become: yes
+  notify: Restart PostgreSQL
+
+- name: Enable PostgreSQL extensions
+  community.postgresql.postgresql_ext:
+    name: "{{ item }}"
+    db: "{{ forgejo_db_name }}"
+    state: present
+  become: yes
+  become_user: postgres
+  loop:
+    - pg_trgm
+    - btree_gin
+
+- name: Create PostgreSQL backup script
+  ansible.builtin.template:
+    src: postgres_backup.sh.j2
+    dest: /usr/local/bin/postgres_backup.sh
+    mode: '0755'
+  become: yes
+  when: forgejo_enable_backups | bool

ansible/roles/forgejo/tasks/prepare.yml

@@ -0,0 +1,194 @@
+---
+# System preparation tasks
+
+- name: Update apt cache
+  ansible.builtin.apt:
+    update_cache: yes
+    cache_valid_time: 3600
+  become: yes
+
+- name: Upgrade all packages
+  ansible.builtin.apt:
+    upgrade: safe
+  become: yes
+  tags:
+    - upgrade
+
+- name: Install system packages
+  ansible.builtin.apt:
+    name: "{{ system_packages }}"
+    state: present
+  become: yes
+
+- name: Check if Forgejo group exists
+  ansible.builtin.getent:
+    database: group
+    key: "{{ forgejo_group }}"
+  register: forgejo_group_check
+  ignore_errors: yes
+  become: yes
+
+- name: Create Forgejo system group
+  ansible.builtin.group:
+    name: "{{ forgejo_group }}"
+    gid: "{{ forgejo_gid }}"
+    system: yes
+    state: present
+  become: yes
+  when: forgejo_group_check.failed | default(false)
+
+- name: Ensure Forgejo group exists (if already created with different GID)
+  ansible.builtin.group:
+    name: "{{ forgejo_group }}"
+    system: yes
+    state: present
+  become: yes
+  when: not (forgejo_group_check.failed | default(false))
+
+- name: Check if Forgejo user exists
+  ansible.builtin.getent:
+    database: passwd
+    key: "{{ forgejo_user }}"
+  register: forgejo_user_check
+  ignore_errors: yes
+  become: yes
+
+- name: Create Forgejo system user
+  ansible.builtin.user:
+    name: "{{ forgejo_user }}"
+    uid: "{{ forgejo_uid }}"
+    group: "{{ forgejo_group }}"
+    system: yes
+    shell: /bin/bash
+    home: "{{ forgejo_base_path }}"
+    create_home: no
+    state: present
+  become: yes
+  when: forgejo_user_check.failed | default(false)
+
+- name: Ensure Forgejo user exists (if already created with different UID)
+  ansible.builtin.user:
+    name: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    system: yes
+    shell: /bin/bash
+    home: "{{ forgejo_base_path }}"
+    create_home: no
+    state: present
+  become: yes
+  when: not (forgejo_user_check.failed | default(false))
+
+- name: Create Forgejo directory structure
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+    owner: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    mode: '0755'
+  become: yes
+  loop:
+    - "{{ forgejo_base_path }}"
+    - "{{ forgejo_data_path }}"
+    - "{{ forgejo_config_path }}"
+    - "{{ forgejo_custom_path }}"
+    - "{{ forgejo_backup_path }}"
+    - "{{ forgejo_data_path }}/git"
+    - "{{ forgejo_data_path }}/attachments"
+    - "{{ forgejo_data_path }}/lfs"
+    - "{{ forgejo_data_path }}/avatars"
+
+- name: Configure system limits for Forgejo
+  ansible.builtin.pam_limits:
+    domain: "{{ forgejo_user }}"
+    limit_type: "{{ item.limit_type }}"
+    limit_item: "{{ item.limit_item }}"
+    value: "{{ item.value }}"
+  become: yes
+  loop:
+    - { limit_type: 'soft', limit_item: 'nofile', value: '65535' }
+    - { limit_type: 'hard', limit_item: 'nofile', value: '65535' }
+    - { limit_type: 'soft', limit_item: 'nproc', value: '65535' }
+    - { limit_type: 'hard', limit_item: 'nproc', value: '65535' }
+
+- name: Configure kernel parameters
+  ansible.builtin.sysctl:
+    name: "{{ item.name }}"
+    value: "{{ item.value }}"
+    state: present
+    reload: yes
+  become: yes
+  loop:
+    - { name: 'net.core.somaxconn', value: '1024' }
+    - { name: 'net.ipv4.tcp_max_syn_backlog', value: '2048' }
+    - { name: 'net.ipv4.ip_forward', value: '1' }
+    - { name: 'vm.swappiness', value: '10' }
+    - { name: 'fs.file-max', value: '65535' }
+
+# NOTE: UFW firewall configuration is handled by ufw.yml
+# We only set up minimal rules here for Docker access during deployment
+# The full secure configuration (Tailscale-only SSH) is applied in ufw.yml
+
+- name: Install UFW
+  ansible.builtin.apt:
+    name: ufw
+    state: present
+  become: yes
+  when: ansible_os_family == "Debian"
+
+- name: Allow Docker network to access host services
+  community.general.ufw:
+    rule: allow
+    from_ip: 172.16.0.0/12
+    comment: "Allow Docker containers to access host services (PostgreSQL, etc.)"
+  become: yes
+  when: ansible_os_family == "Debian"
+
+- name: Set timezone to UTC
+  community.general.timezone:
+    name: UTC
+  become: yes
+
+- name: Enable automatic security updates
+  ansible.builtin.apt:
+    name: unattended-upgrades
+    state: present
+  become: yes
+
+- name: Configure unattended upgrades
+  ansible.builtin.copy:
+    dest: /etc/apt/apt.conf.d/50unattended-upgrades
+    content: |
+      Unattended-Upgrade::Allowed-Origins {
+          "${distro_id}:${distro_codename}-security";
+          "${distro_id}ESMApps:${distro_codename}-apps-security";
+          "${distro_id}ESM:${distro_codename}-infra-security";
+      };
+      Unattended-Upgrade::AutoFixInterruptedDpkg "true";
+      Unattended-Upgrade::MinimalSteps "true";
+      Unattended-Upgrade::Remove-Unused-Dependencies "true";
+      Unattended-Upgrade::Automatic-Reboot "false";
+    mode: '0644'
+  become: yes
+
+- name: Ensure SSH is properly configured
+  ansible.builtin.lineinfile:
+    path: /etc/ssh/sshd_config
+    regexp: "{{ item.regexp }}"
+    line: "{{ item.line }}"
+    state: present
+    validate: '/usr/sbin/sshd -t -f %s'
+  become: yes
+  loop:
+    - { regexp: '^PermitRootLogin', line: 'PermitRootLogin prohibit-password' }
+    - { regexp: '^PasswordAuthentication', line: 'PasswordAuthentication no' }
+    - { regexp: '^PubkeyAuthentication', line: 'PubkeyAuthentication yes' }
+  notify: Restart sshd
+  when: ansible_connection != 'local'
+
+- name: Create systemd service for sshd
+  ansible.builtin.systemd:
+    name: sshd
+    enabled: yes
+    state: started
+  become: yes
+  when: ansible_connection != 'local'

ansible/roles/forgejo/tasks/redis.yml

@@ -0,0 +1,40 @@
+---
+# Redis setup tasks
+
+- name: Install Redis
+  ansible.builtin.apt:
+    name:
+      - redis-server
+      - redis-tools
+    state: present
+    update_cache: yes
+  become: yes
+
+- name: Configure Redis
+  ansible.builtin.lineinfile:
+    path: /etc/redis/redis.conf
+    regexp: "{{ item.regexp }}"
+    line: "{{ item.line }}"
+    state: present
+  become: yes
+  loop:
+    - { regexp: '^bind', line: 'bind 127.0.0.1 ::1' }
+    - { regexp: '^protected-mode', line: 'protected-mode yes' }
+    - { regexp: '^maxmemory', line: 'maxmemory 256mb' }
+    - { regexp: '^maxmemory-policy', line: 'maxmemory-policy allkeys-lru' }
+    - { regexp: '^save', line: 'save 900 1' }
+  notify: Restart Redis
+
+- name: Ensure Redis is started and enabled
+  ansible.builtin.systemd:
+    name: redis-server
+    state: started
+    enabled: yes
+  become: yes
+
+- name: Test Redis connection
+  ansible.builtin.command:
+    cmd: redis-cli ping
+  register: redis_ping
+  changed_when: false
+  failed_when: redis_ping.stdout != "PONG"

ansible/roles/forgejo/tasks/ssl.yml

@@ -0,0 +1,29 @@
+---
+# SSL/TLS setup for Caddy
+# Note: Caddy handles Let's Encrypt certificates automatically!
+# This file only sets up log directories and verifies configuration.
+
+- name: Create Caddy log directory
+  ansible.builtin.file:
+    path: /var/log/caddy
+    state: directory
+    owner: caddy
+    group: caddy
+    mode: '0755'
+  become: yes
+
+- name: Verify Caddy is configured for HTTPS
+  ansible.builtin.debug:
+    msg: >
+      Caddy will automatically obtain and renew TLS certificates for {{ forgejo_domain }}
+      using Let's Encrypt. The email {{ letsencrypt_email }} will be used for renewal
+      notifications. No manual certificate management is required.
+
+- name: Ensure Caddy data directory exists (for certificates)
+  ansible.builtin.file:
+    path: /var/lib/caddy/.local/share/caddy
+    state: directory
+    owner: caddy
+    group: caddy
+    mode: '0700'
+  become: yes

ansible/roles/forgejo/tasks/tailscale.yml

@@ -0,0 +1,76 @@
+---
+# Tailscale VPN installation and configuration
+# Provides secure access to SSH and internal services
+
+- name: Install prerequisites for Tailscale
+  ansible.builtin.apt:
+    name:
+      - curl
+      - gnupg
+      - apt-transport-https
+    state: present
+    update_cache: yes
+  become: yes
+
+- name: Add Tailscale GPG key
+  ansible.builtin.shell: |
+    curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/noble.noarmor.gpg | tee /usr/share/keyrings/tailscale-archive-keyring.gpg > /dev/null
+  args:
+    creates: /usr/share/keyrings/tailscale-archive-keyring.gpg
+  become: yes
+
+- name: Add Tailscale repository
+  ansible.builtin.shell: |
+    curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/noble.tailscale-keyring.list | tee /etc/apt/sources.list.d/tailscale.list > /dev/null
+  args:
+    creates: /etc/apt/sources.list.d/tailscale.list
+  become: yes
+
+- name: Install Tailscale
+  ansible.builtin.apt:
+    name: tailscale
+    state: present
+    update_cache: yes
+  become: yes
+
+- name: Enable Tailscale service
+  ansible.builtin.systemd:
+    name: tailscaled
+    state: started
+    enabled: yes
+  become: yes
+
+- name: Check if Tailscale is already authenticated
+  ansible.builtin.command: tailscale status
+  register: tailscale_status
+  ignore_errors: yes
+  changed_when: false
+  become: yes
+
+- name: Display Tailscale authentication instructions
+  ansible.builtin.debug:
+    msg: |
+      ===============================================================
+      TAILSCALE AUTHENTICATION REQUIRED
+      ===============================================================
+
+      Tailscale is installed but needs to be authenticated.
+
+      SSH into the server and run:
+        sudo tailscale up --ssh
+
+      This will:
+        1. Open a browser URL for authentication
+        2. Connect to your Tailnet
+        3. Enable Tailscale SSH (optional but recommended)
+
+      For headless servers, use an auth key:
+        sudo tailscale up --authkey=tskey-auth-XXXXX
+
+      Generate an auth key at: https://login.tailscale.com/admin/settings/keys
+
+      After authentication, you can access this server via:
+        - Tailscale IP (shown in 'tailscale ip')
+        - Tailscale hostname (from admin console)
+      ===============================================================
+  when: tailscale_status.rc != 0

ansible/roles/forgejo/tasks/ufw.yml

@@ -0,0 +1,142 @@
+---
+# UFW Firewall configuration for Forgejo
+# Restricts SSH access to Tailscale interface only
+# Only exposes HTTP/HTTPS to the public internet
+
+- name: Install UFW
+  ansible.builtin.apt:
+    name: ufw
+    state: present
+    update_cache: yes
+  become: yes
+  tags:
+    - install
+    - ufw
+
+- name: Deploy Forgejo UFW application profile
+  ansible.builtin.template:
+    src: ufw-forgejo.j2
+    dest: /etc/ufw/applications.d/forgejo
+    owner: root
+    group: root
+    mode: '0644'
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Reset UFW to default (clean slate)
+  community.general.ufw:
+    state: reset
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Set default incoming policy to deny
+  community.general.ufw:
+    direction: incoming
+    policy: deny
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Set default outgoing policy to allow
+  community.general.ufw:
+    direction: outgoing
+    policy: allow
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Allow all traffic on Tailscale interface
+  community.general.ufw:
+    rule: allow
+    interface: "{{ tailscale_interface }}"
+    direction: in
+    comment: "Allow all Tailscale traffic (SSH, monitoring, internal services)"
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Allow Docker network to access host services
+  community.general.ufw:
+    rule: allow
+    from_ip: 172.16.0.0/12
+    comment: "Allow Docker containers to access host services (PostgreSQL, etc.)"
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+# Public-facing ports (Caddy handles HTTPS)
+- name: Allow HTTP (Caddy)
+  community.general.ufw:
+    rule: allow
+    port: "80"
+    proto: tcp
+    comment: "HTTP - Caddy (redirects to HTTPS)"
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Allow HTTPS (Caddy)
+  community.general.ufw:
+    rule: allow
+    port: "443"
+    proto: tcp
+    comment: "HTTPS - Caddy/Forgejo"
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+# Git SSH is only accessible via Tailscale (through the interface rule above)
+# Regular SSH is only accessible via Tailscale (through the interface rule above)
+
+- name: Enable UFW logging
+  community.general.ufw:
+    logging: "on"
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Enable UFW
+  community.general.ufw:
+    state: enabled
+  become: yes
+  tags:
+    - configure
+    - ufw
+
+- name: Display UFW security configuration
+  ansible.builtin.debug:
+    msg: |
+      ===============================================================
+      FIREWALL CONFIGURED - SECURITY SUMMARY
+      ===============================================================
+
+      PUBLIC ACCESS (from anywhere):
+        - Port 80/tcp  (HTTP - redirects to HTTPS)
+        - Port 443/tcp (HTTPS - Forgejo web interface)
+
+      TAILSCALE-ONLY ACCESS (via {{ tailscale_interface }}):
+        - Port 22/tcp   (SSH - system administration)
+        - Port 2222/tcp (Git SSH - clone/push/pull)
+        - Port 3000/tcp (Forgejo internal - for debugging)
+        - Port 9090/tcp (Prometheus - if enabled)
+        - All other internal services
+
+      Git clone URLs:
+        - HTTPS (public): https://{{ forgejo_domain }}/user/repo.git
+        - SSH (Tailscale): git@<tailscale-hostname>:user/repo.git
+
+      To access SSH after this change:
+        ssh root@<tailscale-ip-or-hostname>
+
+      ===============================================================

ansible/roles/forgejo/tasks/volume.yml

@@ -0,0 +1,60 @@
+---
+# External volume setup tasks
+
+- name: Check if volume device exists
+  ansible.builtin.stat:
+    path: "{{ forgejo_volume_device }}"
+  register: volume_device
+
+- name: Fail if volume device not found
+  ansible.builtin.fail:
+    msg: "Volume device {{ forgejo_volume_device }} not found"
+  when: not volume_device.stat.exists
+
+- name: Check if volume is already formatted
+  ansible.builtin.command:
+    cmd: "blkid {{ forgejo_volume_device }}"
+  register: volume_formatted
+  changed_when: false
+  failed_when: false
+
+- name: Format volume with ext4
+  ansible.builtin.filesystem:
+    fstype: ext4
+    dev: "{{ forgejo_volume_device }}"
+  become: yes
+  when: volume_formatted.rc != 0
+
+- name: Create mount point
+  ansible.builtin.file:
+    path: "{{ forgejo_volume_mount }}"
+    state: directory
+    mode: '0755'
+  become: yes
+
+- name: Mount volume
+  ansible.posix.mount:
+    path: "{{ forgejo_volume_mount }}"
+    src: "{{ forgejo_volume_device }}"
+    fstype: ext4
+    opts: defaults,nofail
+    state: mounted
+  become: yes
+
+- name: Update data path to use volume
+  ansible.builtin.set_fact:
+    forgejo_data_path: "{{ forgejo_volume_mount }}/data"
+
+- name: Create data directories on volume
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+    owner: "{{ forgejo_user }}"
+    group: "{{ forgejo_group }}"
+    mode: '0755'
+  become: yes
+  loop:
+    - "{{ forgejo_data_path }}"
+    - "{{ forgejo_data_path }}/git"
+    - "{{ forgejo_data_path }}/attachments"
+    - "{{ forgejo_data_path }}/lfs"