doc: lint & enhancements
This commit is contained in:
Clément Désiles
parent
229f9f6b5d
commit
f385efca84
31
README.md
31
README.md
@ -6,6 +6,33 @@ This project is designed for personal/familial scale maintenance, if you find th
|
||||
|
||||
This is a good playground to learn and I encourage you to adapt these roles to your needs. While they might not be production-ready for all environments, I'm open to adapting them for [Ansible Galaxy](<(https://galaxy.ansible.com)>) if there's community interest!
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
**Platform Support:** Arch Linux, Debian/Ubuntu
|
||||
|
||||
**Core Design:**
|
||||
|
||||
- A unique system administrator (`{{ ansible_user }}`)
|
||||
- Security hardened sshd
|
||||
- Shared services pattern: Single PostgreSQL and Valkey (Redis) instances serve all services
|
||||
- Rootless Podman: Containers run as `{{ ansible_user }}` (daemonless, `sudo podman ps` shows nothing)
|
||||
- User systemd services: `systemctl --user status <service>` with lingering enabled
|
||||
- Nginx reverse proxy for web services
|
||||
|
||||
**Available Services:**
|
||||
|
||||
| Service | Description |
|
||||
| ----------- | -------------------------------------------------------- |
|
||||
| dns | Unbound caching DNS + Pi-hole ad blocking + VPN resolver |
|
||||
| nfs | Network file system server |
|
||||
| zfs | ZFS installation and management |
|
||||
| uptime-kuma | Uptime monitoring |
|
||||
| ntfy | Notification server |
|
||||
| gitea | Git server |
|
||||
| immich | Photo management |
|
||||
| static-web | Static website hosting |
|
||||
| vpn | WireGuard server |
|
||||
|
||||
## Requirements
|
||||
|
||||
Base tools:
|
||||
@ -36,7 +63,7 @@ ansible-playbook -i inventory/hosts.yml playbook.yml \
|
||||
--ask-become-pass
|
||||
```
|
||||
|
||||
You can also unlock your key system wide to simplify your calls:
|
||||
You can also call you ssh agent to unlock your key prior to simplify your calls:
|
||||
|
||||
```sh
|
||||
ssh-add ~/.ssh/my_key
|
||||
@ -45,7 +72,7 @@ ansible-playbook -i inventory/hosts.yml playbook.yml \
|
||||
--ask-become-pass
|
||||
```
|
||||
|
||||
## Target devices configuration
|
||||
## Target configuration
|
||||
|
||||
Requirements:
|
||||
|
||||
|
||||
@ -20,10 +20,10 @@ Sync time from public NTP pools, don't serve time to others:
|
||||
# host_vars/example.yml
|
||||
ntp_timezone: "Europe/Paris"
|
||||
ntp_pools:
|
||||
- "0.fr.pool.ntp.org"
|
||||
- "1.fr.pool.ntp.org"
|
||||
- "2.fr.pool.ntp.org"
|
||||
- "3.fr.pool.ntp.org"
|
||||
- "0.fr.pool.ntp.org"
|
||||
- "1.fr.pool.ntp.org"
|
||||
- "2.fr.pool.ntp.org"
|
||||
- "3.fr.pool.ntp.org"
|
||||
```
|
||||
|
||||
### Server mode
|
||||
@ -35,20 +35,20 @@ Serve time to local network:
|
||||
ntp_timezone: "UTC"
|
||||
ntp_server_enabled: true
|
||||
ntp_allowed_networks:
|
||||
- 192.168.1.0/24 # Configures both chrony and firewall
|
||||
- 192.168.27.0/27
|
||||
- 192.168.1.0/24 # Configures both chrony and firewall
|
||||
- 192.168.27.0/27
|
||||
```
|
||||
|
||||
### Client syncing from local server
|
||||
|
||||
```yaml
|
||||
# host_vars/client.yml
|
||||
ntp_pools: [] # Don't use public pools
|
||||
ntp_pools: [] # Don't use public pools
|
||||
ntp_servers:
|
||||
- server: ntp.local.lan
|
||||
options: iburst prefer
|
||||
- server: 192.168.1.1
|
||||
options: iburst
|
||||
- server: ntp.local.lan
|
||||
options: iburst prefer
|
||||
- server: 192.168.1.1
|
||||
options: iburst
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
@ -2,20 +2,6 @@
|
||||
|
||||
Deploy static websites from Git repositories with Nginx.
|
||||
|
||||
## Features
|
||||
|
||||
- Clone static sites from Git repositories
|
||||
- Automatic Nginx vhost configuration
|
||||
- HTTPS enabled by default with Let's Encrypt
|
||||
- Support for build commands (npm, hugo, jekyll, etc.)
|
||||
- Subdirectory serving (for built assets)
|
||||
- Static file caching
|
||||
- Security headers (including HSTS for HTTPS)
|
||||
|
||||
## Dependencies
|
||||
|
||||
- nginx role (automatically included via meta/main.yml)
|
||||
|
||||
## Variables
|
||||
|
||||
See [defaults/main.yml](defaults/main.yml)
|
||||
@ -24,82 +10,17 @@ See [defaults/main.yml](defaults/main.yml)
|
||||
|
||||
```yaml
|
||||
static_web_sites:
|
||||
"portfolio.example.fr":
|
||||
git_repo: "https://github.com/example/portfolio.git"
|
||||
git_branch: "main" # Optional, defaults to main
|
||||
git_depth: 1 # Optional, shallow clone
|
||||
build_command: "npm install && npm run build" # Optional
|
||||
root_dir: "dist" # Optional, serve subdirectory
|
||||
ssl_enabled: true # Optional, defaults to true (HTTPS)
|
||||
"portfolio.example.fr":
|
||||
git_repo: "https://github.com/example/portfolio.git"
|
||||
git_branch: "main" # Optional, defaults to main
|
||||
git_depth: 1 # Optional, shallow clone
|
||||
build_command: "npm install && npm run build" # Optional
|
||||
root_dir: "dist" # Optional, serve subdirectory
|
||||
ssl_enabled: true # Optional, defaults to true (HTTPS)
|
||||
|
||||
"blog.example.com":
|
||||
git_repo: "https://github.com/example/blog.git"
|
||||
# ssl_enabled defaults to true, set to false for HTTP only
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
**Inventory (host_vars or group_vars):**
|
||||
|
||||
```yaml
|
||||
static_web_sites:
|
||||
"portfolio.example.fr":
|
||||
git_repo: "https://github.com/username/portfolio.git"
|
||||
|
||||
"docs.example.com":
|
||||
git_repo: "https://github.com/company/documentation.git"
|
||||
git_branch: "gh-pages"
|
||||
root_dir: "_site"
|
||||
```
|
||||
|
||||
**Playbook:**
|
||||
|
||||
```yaml
|
||||
- hosts: webservers
|
||||
roles:
|
||||
- static-web
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
Sites are deployed to `/var/www/static/<hostname>/`
|
||||
|
||||
Example:
|
||||
```
|
||||
/var/www/static/
|
||||
├── portfolio.example.fr/
|
||||
│ └── index.html
|
||||
└── blog.example.com/
|
||||
├── _site/ # Built assets (if root_dir specified)
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Advanced Examples
|
||||
|
||||
**Hugo site:**
|
||||
```yaml
|
||||
static_web_sites:
|
||||
"blog.example.com":
|
||||
git_repo: "https://github.com/example/hugo-blog.git"
|
||||
build_command: "hugo --minify"
|
||||
root_dir: "public"
|
||||
```
|
||||
|
||||
**React app:**
|
||||
```yaml
|
||||
static_web_sites:
|
||||
"app.example.com":
|
||||
git_repo: "https://github.com/example/react-app.git"
|
||||
build_command: "npm ci && npm run build"
|
||||
root_dir: "build"
|
||||
```
|
||||
|
||||
## Updating Sites
|
||||
|
||||
Re-run the playbook to pull latest changes:
|
||||
|
||||
```bash
|
||||
ansible-playbook -i inventory playbook.yml --tags static-web
|
||||
"blog.example.com":
|
||||
git_repo: "https://github.com/example/blog.git"
|
||||
# ssl_enabled defaults to true, set to false for HTTP only
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
@ -17,7 +17,8 @@
|
||||
when: zfs_pools is defined
|
||||
|
||||
- name: Creating basic zpool(s)
|
||||
ansible.builtin.command: "zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
|
||||
ansible.builtin.command:
|
||||
"zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
|
||||
item.devices|join (' ') }}"
|
||||
with_items: "{{ zfs_pools }}"
|
||||
when:
|
||||
@ -28,7 +29,8 @@
|
||||
- item.devices[0] not in zpool_devices.stdout
|
||||
|
||||
- name: Creating mirror/zraid zpool(s)
|
||||
ansible.builtin.command: "zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
|
||||
ansible.builtin.command:
|
||||
"zpool create {{ '-o '+ item.options.items() |map('join', '=') | join (' -o ') if item.options is defined else '' }} {{ item.name }} {{
|
||||
item.type }} {{ item.devices|join (' ') }}"
|
||||
with_items: "{{ zfs_pools }}"
|
||||
when:
|
||||
|
||||
@ -24,9 +24,18 @@
|
||||
update: true
|
||||
version: master
|
||||
loop:
|
||||
- { repo: https://github.com/zsh-users/zsh-syntax-highlighting.git, dest: "{{ zsh_plugins_path }}/zsh-syntax-highlighting" }
|
||||
- { repo: https://github.com/zsh-users/zsh-autosuggestions.git, dest: "{{ zsh_plugins_path }}/zsh-autosuggestions" }
|
||||
- { repo: https://github.com/romkatv/powerlevel10k.git, dest: "{{ zsh_plugins_path }}/powerlevel10k" }
|
||||
- {
|
||||
repo: https://github.com/zsh-users/zsh-syntax-highlighting.git,
|
||||
dest: "{{ zsh_plugins_path }}/zsh-syntax-highlighting",
|
||||
}
|
||||
- {
|
||||
repo: https://github.com/zsh-users/zsh-autosuggestions.git,
|
||||
dest: "{{ zsh_plugins_path }}/zsh-autosuggestions",
|
||||
}
|
||||
- {
|
||||
repo: https://github.com/romkatv/powerlevel10k.git,
|
||||
dest: "{{ zsh_plugins_path }}/powerlevel10k",
|
||||
}
|
||||
|
||||
- name: Assert plugins are available for any user
|
||||
ansible.builtin.file:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user