diff --git a/.claude/commands/improve-docs.md b/.claude/commands/improve-docs.md new file mode 100644 index 00000000..5d267fe1 --- /dev/null +++ b/.claude/commands/improve-docs.md @@ -0,0 +1,60 @@ +# Improve Documentation + +## Variables + +FILES: $ARGUMENTS + +## Instructions + +Improve the spelling, grammar, and style of markdown-based documentation files in this repository. + +### Part 1 - Identify Documentation Files + +1. If FILES is provided, use those specific files. Otherwise, find all markdown files in the repository using: + - Search for files with `.md` extension + - Focus on documentation directories like `docs/`, `README.md`, and other markdown files + - Exclude generated files, third-party code, and non-documentation markdown + +### Part 2 - Analyze and Improve Each File + +For each documentation file: + +1. **Read the file** to understand its content and purpose +2. **Check for issues**: + - Spelling errors + - Grammar mistakes + - Inconsistent formatting + - Awkward phrasing or unclear sentences + - Missing or incorrect punctuation + - Inconsistent heading styles + - Broken links or references +3. **Apply fixes**: + - Correct spelling errors + - Improve grammar and sentence structure + - Enhance clarity and readability + - Ensure consistent markdown formatting + - Fix any broken internal links + - Maintain the original meaning and technical accuracy + +### Part 3 - Quality Assurance + +1. After improving each file, re-read it to ensure: + - The content remains technically accurate + - The tone and style are appropriate for documentation + - Links and references still work + - Code examples (if any) are still valid +2. Run any available linting tools on the modified files (e.g., markdownlint if configured) +3. Verify that the changes don't break any documentation build processes + +### Part 4 - Summary + +Provide a summary of all changes made, including: +- Files modified +- Types of improvements made (spelling, grammar, style) +- Any files that couldn't be improved and why + +Notes: +- Preserve technical terminology and code snippets exactly as they are +- Maintain the existing documentation structure and organization +- Focus on clarity and professionalism while keeping the original voice +- If unsure about a technical term or concept, leave it unchanged diff --git a/.claude/settings.json b/.claude/settings.json index 75e87d52..de084fba 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -13,6 +13,7 @@ "WebFetch(domain:docs.linuxserver.io)", "Bash(scripts/labctl.py service config:*)", "Bash(scripts/labctl.py service pull:*)", + "Bash(scripts/labctl.py service logs:*)", "Bash(pre-commit run:*)", "Bash(task lint-app)", "Bash(task lint)" diff --git a/.flake8 b/.flake8 new file mode 100644 index 00000000..d9775c5b --- /dev/null +++ b/.flake8 @@ -0,0 +1,2 @@ +[flake8] +extend-ignore = E501 # Line too long diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 23934283..fdcdc372 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -49,7 +49,7 @@ repos: # Linter - https://docs.astral.sh/ruff/linter/ - id: ruff-check args: ["--fix"] - # TODO Enable after pendling MRs are merged + # TODO Enable after pending MRs are merged # Formatter - https://docs.astral.sh/ruff/formatter/ # - id: ruff-format @@ -88,7 +88,7 @@ repos: # Add '--fix' parameter to ansiblelint to fix (some) issues - https://ansible.readthedocs.io/projects/lint/autofix/ # Add '-v' parameter to ansiblelint for verbose mode - repo: https://github.com/ansible-community/ansible-lint - rev: v25.11.0 # More recent version causes Python incompatibility - https://github.com/ansible/ansible-lint/pull/4796 + rev: v25.9.0 # More recent version than v25.9.0 causes Python incompatibility - https://github.com/ansible/ansible-lint/pull/4796 hooks: - id: ansible-lint files: ^ansible/ diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..8555908d --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,13 @@ +{ + "github.copilot.enable": { + "properties": false + }, + "spellright.language": [ + "en" + ], + "spellright.documentTypes": [ + "markdown", + "latex", + "plaintext" + ] +} diff --git a/AGENTS.md b/AGENTS.md index 85748707..8448b9c0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Repository Overview This repository contains Infrastructure as Code (IaC) configuration for a home infrastructure setup. The main goals are: -- Creating a local, self-hosted environment for various services minimizing reliance on cloud providers +- Creating a local, self-hosted environment for various services, minimizing reliance on cloud providers - Learning and organizing knowledge, best practices, and tool documentation ## Key Commands diff --git a/README.md b/README.md index 985d74a7..9a8bc3e1 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@ ![Dev Container workflow](https://img.shields.io/github/actions/workflow/status/bubacoder/infra/devcontainer.yml?label=devcontainer) ![Pre-commit checks workflow](https://img.shields.io/github/actions/workflow/status/bubacoder/infra/pre-commit.yml?label=checks) -This repository contains the Infrastructure as Code (IaC) configuration and documentation for my home infrastructure. The main goals of this ever-evolving setup are: -- Create a local, self-hosted environment for various services and applications, minimizing reliance on external cloud providers. +This repository contains the Infrastructure as Code (IaC) configuration and documentation for a home infrastructure setup. The main goals are: +- Creating a local, self-hosted environment for various services and applications, minimizing reliance on external cloud providers. - Learning and organizing knowledge, best practices, and tool documentation into a single repository. ## Table of Contents @@ -48,22 +48,22 @@ The key components of this infrastructure include: The long-term goal is to reduce these dependencies and provide offline alternatives. -| Name | Description | Remarks | -| ------------------------------------------------------------------------ | -------------------------------------- | ----------------------------------------------------------------------- | -| Docker images | All services are running as containers | Downloaded on first use | -| Plugins, Modules (e.g. Crowdsec) | Various plugins for services | Downloaded on first use. TODO create inventory | -| Large Language Models | Optional, used by Ollama | Downloaded on first use | -| [OVHcloud](https://www.ovhcloud.com/en/) (or other registrar) | Domain Name registration | Required for remote access and TLS certificates. TODO document fallback | -| [Cloudflare](https://www.cloudflare.com/) | DNS zone administration, tunnel | Optional, for remote access | -| [Let's Encrypt](https://letsencrypt.org/) | TLS certificates (managed by Traefik) | Required. TODO document local CA setup for fallback | -| [Backblaze B2](https://www.backblaze.com/cloud-storage) | Backup storage | Optional, local backup also configured | -| [CrowdSec](https://app.crowdsec.net/) | Crowd-sourced IP blocklist | Optional, security service, can be disabled | -| [Azure](https://azure.microsoft.com/) | Temporal VM, storage | Optional, not used by any lab components | -| [Homepage Icons](https://github.com/walkxcode/dashboard-icons/tree/main) | Icon set for the services | Optional, hosted on a CDN. TODO host locally | +| Name | Description | Remarks | +| ------------------------------------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------- | +| Docker images | All services run as containers | Downloaded on first use | +| Plugins, Modules (e.g., CrowdSec) | Various plugins for services | Downloaded on first use. TODO: create inventory | +| Large Language Models | Optional, used by Ollama | Downloaded on first use | +| [OVHcloud](https://www.ovhcloud.com/en/) (or other registrar) | Domain name registration | Required for remote access and TLS certificates. TODO: document fallback | +| [Cloudflare](https://www.cloudflare.com/) | DNS zone administration, tunnel | Optional, for remote access | +| [Let's Encrypt](https://letsencrypt.org/) | TLS certificates (managed by Traefik) | Required. TODO: document local CA setup for fallback | +| [Backblaze B2](https://www.backblaze.com/cloud-storage) | Backup storage | Optional, local backup also configured | +| [CrowdSec](https://app.crowdsec.net/) | Crowd-sourced IP blocklist | Optional, security service, can be disabled | +| [Azure](https://azure.microsoft.com/) | Temporary VM, storage | Optional, not used by any lab components | +| [Homepage Icons](https://github.com/walkxcode/dashboard-icons/tree/main) | Icon set for the services | Optional, hosted on a CDN. TODO: host locally | ## Getting Started -The recommended configuration is to setup Proxmox VE and install a Debian- or Ubuntu-based VM to host the Docker services. +The recommended configuration is to set up Proxmox VE and install a Debian- or Ubuntu-based VM to host the Docker services. -> See [Getting Started](docs/setup.md) diff --git a/ansible/README.md b/ansible/README.md index 45c616c9..022c757f 100644 --- a/ansible/README.md +++ b/ansible/README.md @@ -22,7 +22,7 @@ https://www.ansible.com/ ## Setup steps -1. Instal Ansible on the admin workstation with `bootstrap-ansible.sh`. (See: [Ansible control node](https://docs.ansible.com/ansible/latest/network/getting_started/basic_concepts.html#control-node)) +1. Install Ansible on the admin workstation with `bootstrap-ansible.sh`. (See: [Ansible control node](https://docs.ansible.com/ansible/latest/network/getting_started/basic_concepts.html#control-node)) 2. Configure variables in `inventory/group_vars/` 3. Add hosts to `inventory/inventory.yaml` 4. Assign roles to hosts in `playbooks/` diff --git a/docker/README.md b/docker/README.md index f9c4c4eb..17138f4a 100644 --- a/docker/README.md +++ b/docker/README.md @@ -16,7 +16,7 @@ For additional services to host, check [awesome-selfhosted](https://github.com/a In the `config/docker` subfolder multiple Docker hosts can be defined. Configuration files: -- Host-specific settings: `config/docker//.env` -> See [Setting Started -> Configure Docker environment files][setup] for more details. (These files are not committed to the repo - backup them separately!) +- Host-specific settings: `config/docker//.env` -> See [Getting Started -> Configure Docker environment files](../docs/setup.md#5-configure-docker-environment-files) for more details. (These files are not committed to the repo - backup them separately!) - Configure which services to start (`state: up`) or stop (`state: down`): `config/docker//services.yaml` ## Services diff --git a/docker/security/traefik.yaml b/docker/security/traefik.yaml index 6baba90d..4caf3d75 100644 --- a/docker/security/traefik.yaml +++ b/docker/security/traefik.yaml @@ -8,7 +8,7 @@ name: traefik services: traefik: - image: traefik:v3.6.0 + image: traefik:v3.6.2 container_name: traefik restart: unless-stopped environment: diff --git a/docs/ai/README.md b/docs/ai/README.md index d904ac2f..0eba0d0d 100644 --- a/docs/ai/README.md +++ b/docs/ai/README.md @@ -12,7 +12,7 @@ ### Hardware requirements -- CPU and GPU mode is supported +- CPU and GPU modes are supported - You should have at least 8 GB of RAM available to run the 7B models, 16 GB to run the 13B models, and 32 GB to run the 33B models. - On Apple M1 and higher Ollama performs great with 7B models due to the [Unified memory architecture](https://en.wikipedia.org/wiki/Apple_M1#Memory) - High memory bandwidth (typically GPU) is the top priority to achieve good performance diff --git a/docs/runbooks.md b/docs/runbooks.md index 32152ce6..e37b2e1e 100644 --- a/docs/runbooks.md +++ b/docs/runbooks.md @@ -13,7 +13,7 @@ Hosts involved: Steps: - OLD: Install the new host using `proxmox/create-ubuntu-server-vm.sh` -- OLD: Apply ansible using `ansible/apply-homelab.sh` +- OLD: Apply Ansible using `ansible/apply-homelab.sh` - OLD: Transfer container images to save bandwidth (Optional, see: [Docker](../docker/README.md)) Optional: copy **Server Host Key**, an RSA, ED25519, or ECDSA private key diff --git a/docs/setup.md b/docs/setup.md index 546ddbb5..d98fc0ef 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -12,19 +12,19 @@ - [6. Configure core services](#6-configure-core-services) - [7. Start the containers](#7-start-the-containers) - [8. Configure the router](#8-configure-the-router) - - [9. Configure addition infrastructure services](#9-configure-addition-infrastructure-services) + - [9. Configure additional infrastructure services](#9-configure-additional-infrastructure-services) ## Online service setup -This setup uses a public Domain Name to allow publishing local services and to have a recognized TLS certificate. -An alternative is to use free subdomains (e.g. duckdns.org) but its support is not included in this setup. +This setup uses a public domain name to allow publishing local services and to have a recognized TLS certificate. +An alternative is to use free subdomains (e.g. duckdns.org) but their support is not included in this setup. 1. Register a Domain Name, e.g. at [OVHcloud](https://www.ovhcloud.com/en/) - but the registrar does not matter, see next step 2. Transfer the DNS Zone administration to [Cloudflare](https://www.cloudflare.com/application-services/products/dns/) - Traefik reverse proxy certificate renewal is configured to use Cloudflare ## Local configuration -The recommended setup is to setup Proxmox VE and install a Debian- or Ubuntu-based VM to host the Docker services. +The recommended setup is to install Proxmox VE and deploy a Debian- or Ubuntu-based VM to host the Docker services. For development and administrative purposes, a separate VM can be used with additional tools installed. This separation from the Docker host is a best practice, but to simplify the setup these two roles can be unified. ### 1. Install Proxmox Virtual Environment @@ -35,13 +35,13 @@ For development and administrative purposes, a separate VM can be used with addi #### Option A - Use devcontainer (easy method) -The repository includes a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) configuration. -Using Visual Studio Code, the [Dev Containers Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and Docker the development (e.g. adding more services, building the documentation) and administration tasks (e.g. running an Ansible playbook) can be performed on any environment without additional software installation. +The repository includes a [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) configuration. +Using Visual Studio Code, the [Dev Containers Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and Docker, the development (e.g. adding more services, building the documentation) and administration tasks (e.g. running an Ansible playbook) can be performed on any environment without additional software installation. Follow the [Dev Containers tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) to get started. For troubleshooting, tips and tricks see [Dev Containers](../.devcontainer/README.md). -Note: the resulting container image is pretty large (4+ GB) as it includes all software configured in `ansible/inventory/group_vars/debian/vars.yaml`. +Note: The resulting container image is quite large (4+ GB) as it includes all software configured in `ansible/inventory/group_vars/debian/vars.yaml`. #### Option B - Use a dev/admin host @@ -58,12 +58,12 @@ Steps: ### 3. Install Ubuntu Server VM (Docker host) -Edit the parameters and use the `infra/proxmox/create-ubuntu-server-vm.sh` script to automatically create an Ubuntu Server LTS virtual machine and start the OS installation. +Edit the parameters and use the `proxmox/create-ubuntu-server-vm.sh` script to automatically create an Ubuntu Server LTS virtual machine and start the OS installation. Note - Alternatives: -- Create the VM on the Proxmox GUI, download and attach the installer CD and proceed with manual installation (who does that?) +- Create the VM using the Proxmox web interface, download and attach the installer ISO, then proceed with manual installation - Use Terraform to deploy the VM via the [Proxmox Terraform provider](https://registry.terraform.io/providers/Telmate/proxmox/latest/docs) -- Install Ubuntu as an LXC container (there could be some limitations) +- Install Ubuntu as an LXC container (note that there may be some limitations) ### 4. Install and configure the required software using Ansible @@ -104,9 +104,9 @@ config/docker ### 6. Configure core services -TODO Separate core services, like Traefik, Homepage +TODO: Separate core services, like Traefik and Homepage -TODO Describe the minimally required (core) service configuration +TODO: Describe the minimally required core service configuration ### 7. Start the containers @@ -132,9 +132,9 @@ ipconfig /all ipconfig /release && ipconfig /renew ``` -### 9. Configure addition infrastructure services +### 9. Configure additional infrastructure services -TODO Describe configuration +TODO: Describe configuration - AdGuard: local domain, router DHCP - Cloudflare diff --git a/scripts/copy-repo-template.sh b/scripts/copy-repo-template.sh index 735c19a5..08dbddc1 100755 --- a/scripts/copy-repo-template.sh +++ b/scripts/copy-repo-template.sh @@ -3,7 +3,7 @@ set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" SOURCE="$(dirname "$SCRIPT_DIR")" -TARGET="$(dirname "$SCRIPT_DIR")/../../repo-template" +TARGET="$(dirname "$SCRIPT_DIR")/../repo-template" # List of files to copy files_to_copy=(