feat: introduce immich

2025-11-14 00:23:03 +01:00
parent 96abbbefa2
commit 3ab48b93a6
20 changed files with 1225 additions and 128 deletions
@@ -0,0 +1,213 @@
+# Nginx Role
+
+This Ansible role installs and configures Nginx as a reverse proxy for web applications.
+
+## Features
+
+- Installs Nginx
+- Configurable worker processes and connections
+- Gzip compression support
+- SSL/TLS configuration
+- Modular vhost configuration via `/etc/nginx/conf.d/`
+- Zero-downtime reloads
+
+## Requirements
+
+- Systemd-based Linux distribution
+- Root/sudo access
+
+## Role Variables
+
+See `defaults/main.yml` for all available variables and their default values.
+
+### Key Configuration
+
+The role provides sensible defaults for worker processes, connection limits, upload sizes, compression, and SSL/TLS settings. Override as needed in your inventory.
+
+## Dependencies
+
+None.
+
+## Example Playbook
+
+### Basic Installation
+
+```yaml
+---
+- hosts: servers
+  become: true
+  roles:
+    - role: nginx
+```
+
+### Custom Configuration
+
+```yaml
+---
+- hosts: servers
+  become: true
+  roles:
+    - role: nginx
+      vars:
+        nginx_worker_processes: 4
+        nginx_worker_connections: 2048
+        nginx_client_max_body_size: 500M
+```
+
+## Service Management
+
+The role creates handlers for managing nginx:
+
+```yaml
+notify: Reload nginx   # Graceful reload (zero downtime)
+notify: Restart nginx  # Full restart
+```
+
+## Vhost Configuration Pattern
+
+This role is designed to work with service-specific vhost configurations. Each service role should:
+
+1. Deploy its vhost config to `/etc/nginx/conf.d/<service>.conf`
+2. Notify the nginx reload handler
+3. Use a variable to enable/disable nginx integration
+
+### Example Service Integration
+
+In your service role (e.g., `immich`):
+
+**defaults/main.yml:**
+```yaml
+immich_nginx_enabled: false
+immich_nginx_hostname: immich.example.com
+```
+
+**tasks/main.yml:**
+```yaml
+- name: Deploy nginx vhost for service
+  ansible.builtin.template:
+    src: nginx-vhost.conf.j2
+    dest: /etc/nginx/conf.d/myservice.conf
+    validate: nginx -t
+  when: myservice_nginx_enabled
+  notify: Reload nginx
+
+- name: Remove nginx vhost when disabled
+  ansible.builtin.file:
+    path: /etc/nginx/conf.d/myservice.conf
+    state: absent
+  when: not myservice_nginx_enabled
+  notify: Reload nginx
+```
+
+**templates/nginx-vhost.conf.j2:**
+```nginx
+server {
+    listen 80;
+    server_name {{ myservice_nginx_hostname }};
+
+    location / {
+        proxy_pass http://127.0.0.1:{{ myservice_port }};
+        proxy_set_header Host $http_host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+**handlers/main.yml:**
+```yaml
+- name: Reload nginx
+  ansible.builtin.systemd:
+    name: nginx
+    state: reloaded
+```
+
+## Independent Deployments
+
+This pattern allows for independent service deployments:
+
+1. **Deploy service A** → Only touches `/etc/nginx/conf.d/serviceA.conf` → Reload nginx
+2. **Deploy service B** → Only touches `/etc/nginx/conf.d/serviceB.conf` → Reload nginx
+3. **No downtime** for other services during deployment
+
+## Log Management
+
+Nginx logs are written to:
+- `/var/log/nginx/access.log` - Access logs
+- `/var/log/nginx/error.log` - Error logs
+
+These are also captured by systemd journal:
+```bash
+# View nginx logs
+journalctl -u nginx -f
+
+# View traditional log files
+tail -f /var/log/nginx/access.log
+tail -f /var/log/nginx/error.log
+```
+
+## Configuration Validation
+
+The role automatically validates nginx configuration before applying changes using `nginx -t`.
+
+Manual validation:
+```bash
+nginx -t                    # Test configuration
+nginx -t -c /path/to/conf  # Test specific config file
+```
+
+## Troubleshooting
+
+### Check nginx status
+```bash
+systemctl status nginx
+```
+
+### Test configuration
+```bash
+nginx -t
+```
+
+### Reload configuration
+```bash
+systemctl reload nginx
+```
+
+### View error logs
+```bash
+journalctl -u nginx -n 100
+# or
+tail -f /var/log/nginx/error.log
+```
+
+### List loaded vhost configs
+```bash
+ls -la /etc/nginx/conf.d/
+```
+
+## SSL/TLS Support
+
+For SSL support, you can:
+
+1. **Manual certificates:** Place certs in `/etc/ssl/` and reference in vhost configs
+2. **Let's Encrypt:** Use certbot or similar tools (can be added to playbook)
+3. **Self-signed:** Generate with `openssl` for testing
+
+The base nginx.conf includes SSL protocol configuration that applies to all vhosts.
+
+## Performance Tuning
+
+Adjust these variables based on your workload:
+
+- `nginx_worker_processes`: Set to number of CPU cores
+- `nginx_worker_connections`: Increase for high traffic (check `ulimit -n`)
+- `nginx_client_max_body_size`: Increase for large file uploads
+
+## License
+
+MIT
+
+## Author Information
+
+Created for managing reverse proxy configurations in NAS/homelab environments.
@@ -0,0 +1,16 @@
+---
+# Nginx configuration directory for service vhosts
+nginx_conf_dir: /etc/nginx/conf.d
+
+# Worker processes (auto = number of CPU cores)
+nginx_worker_processes: auto
+
+# Worker connections
+nginx_worker_connections: 1024
+
+# Client max body size (for file uploads)
+nginx_client_max_body_size: 100M
+
+# SSL configuration (volontarily omit TLSv1.2 here)
+nginx_ssl_protocols: TLSv1.3
+nginx_ssl_prefer_server_ciphers: true
@@ -0,0 +1,10 @@
+---
+- name: Reload nginx
+  ansible.builtin.systemd:
+    name: nginx
+    state: reloaded
+
+- name: Restart nginx
+  ansible.builtin.systemd:
+    name: nginx
+    state: restarted
@@ -0,0 +1,49 @@
+---
+- name: Load OS-specific variables
+  ansible.builtin.include_vars: "{{ item }}"
+  with_first_found:
+    - "{{ ansible_facts['os_family'] }}.yml"
+    - debian.yml
+
+- name: Install nginx
+  ansible.builtin.package:
+    name: nginx
+    state: present
+
+- name: Ensure nginx conf.d directory exists
+  ansible.builtin.file:
+    path: "{{ nginx_conf_dir }}"
+    state: directory
+    owner: root
+    group: root
+    mode: "0755"
+
+- name: Deploy nginx main configuration
+  ansible.builtin.template:
+    src: nginx.conf.j2
+    dest: /etc/nginx/nginx.conf
+    owner: root
+    group: root
+    mode: "0644"
+    validate: nginx -t -c %s
+  notify: Reload nginx
+
+- name: Allow HTTP traffic through firewall
+  community.general.ufw:
+    rule: allow
+    port: "80"
+    proto: tcp
+    comment: Nginx HTTP
+
+- name: Allow HTTPS traffic through firewall
+  community.general.ufw:
+    rule: allow
+    port: "443"
+    proto: tcp
+    comment: Nginx HTTPS
+
+- name: Enable and start nginx service
+  ansible.builtin.systemd:
+    name: nginx
+    enabled: true
+    state: started
@@ -0,0 +1,42 @@
+user {{ nginx_user }};
+worker_processes {{ nginx_worker_processes }};
+error_log /var/log/nginx/error.log;
+pid /run/nginx.pid;
+
+include /usr/share/nginx/modules/*.conf;
+
+events {
+    worker_connections {{ nginx_worker_connections }};
+}
+
+http {
+    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
+                      '$status $body_bytes_sent "$http_referer" '
+                      '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log  /var/log/nginx/access.log  main;
+
+    sendfile            on;
+    tcp_nopush          on;
+    tcp_nodelay         on;
+    keepalive_timeout   65;
+    types_hash_max_size 4096;
+    client_max_body_size {{ nginx_client_max_body_size }};
+
+    include             /etc/nginx/mime.types;
+    default_type        application/octet-stream;
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types text/plain text/css text/xml text/javascript application/json application/javascript application/xml+rss application/rss+xml font/truetype font/opentype application/vnd.ms-fontobject image/svg+xml;
+
+    # SSL configuration
+    ssl_protocols {{ nginx_ssl_protocols }};
+    ssl_prefer_server_ciphers {{ 'on' if nginx_ssl_prefer_server_ciphers else 'off' }};
+
+    # Load modular configuration files from the conf.d directory
+    include {{ nginx_conf_dir }}/*.conf;
+}
@@ -0,0 +1,2 @@
+---
+nginx_user: http