68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
---
|
|
tags:
|
|
- GIT
|
|
- CI/CD
|
|
- CI-CD
|
|
---
|
|
To test and validate your `docker-compose` infrastructure configurations right inside your homelab, you can use Gitea Actions to automatically check your YAML syntax and test your container builds every time you make an edit. [[1](https://mortylen.hashnode.dev/gitea-self-hosted-workflow-action-for-ci), [2](https://ramnode.com/guides/series/gitea-devops/gitea-setup)]
|
|
|
|
Here is how to set up an automated testing pipeline specifically for a homelab Docker Compose repository.
|
|
|
|
🛠️ Step 1: Set Up the Workflow Directory
|
|
|
|
In your homelab Git repository containing your `docker-compose.yml` files, create the specific workflow path: [[1](https://www.stackhero.io/en-CA/services/Docker/documentations/Deploy-with-GitHub-Actions)]
|
|
|
|
- **File path:** `.gitea/workflows/docker-test.yaml`
|
|
|
|
📝 Step 2: Paste the Homelab Validation Template
|
|
|
|
Copy and paste this template into your new file. It is optimized to perform two critical steps: lint your YAML formatting for typos, and dry-run your Docker Compose setup to ensure your container configurations are valid. [[1](https://www.reddit.com/r/docker/comments/1i32i3z/one_large_compose_file/), [2](https://www.docker.com/blog/compose-to-kubernetes-to-cloud-kanvas/)]
|
|
|
|
`name: Docker Compose Validator`
|
|
`run-name: Homelab configuration test by ${{ gitea.actor }} 🛠️`
|
|
|
|
`on:`
|
|
`push:`
|
|
`branches: [ "main", "master" ]`
|
|
`pull_request:`
|
|
`branches: [ "main", "master" ]`
|
|
|
|
`jobs:`
|
|
`validate-and-test:`
|
|
`runs-on: ubuntu-latest`
|
|
|
|
`steps:`
|
|
`# 1. Pull down your homelab repository code`
|
|
`- name: Checkout Repository Code`
|
|
`uses: actions/checkout@v4`
|
|
|
|
`# 2. Check all YAML files for syntax, indentation, and formatting errors`
|
|
`- name: Lint YAML Syntax`
|
|
`uses: https://github.com`
|
|
`with:`
|
|
`file_or_dir: "."`
|
|
|
|
`# 3. Verify that the docker-compose syntax is structurally sound`
|
|
`- name: Verify Compose File Validity`
|
|
`run: |`
|
|
`echo "Checking docker-compose configuration..."`
|
|
`docker compose config`
|
|
|
|
`# 4. Dry-run the build sequence to ensure images and contexts are reachable`
|
|
`- name: Test Build Sequence`
|
|
`run: |`
|
|
`echo "Simulating container build sequence..."`
|
|
`docker compose build`
|
|
|
|
🔍 Breaking Down How This Works for Homelabbers
|
|
|
|
- **YAML Linting:** Homelab configurations frequently break due to an accidental extra space or missing indentation. The `action-yamllint` step scans your files and alerts you to formatting errors before they hit your live system.
|
|
- **`docker compose config`:** This command acts as a built-in validator. It reads your `docker-compose.yml` file, processes any variables, and outputs an error if you have typos in your keys, volume definitions, or network syntax. [[1](https://labex.io/tutorials/docker-how-to-use-docker-compose-config-command-to-validate-and-view-compose-files-555074), [2](https://www.reddit.com/r/docker/comments/13vupxt/switching_from_portainer_to_dockercompose_and/), [3](https://medium.com/@adriansyah1230/mastering-docker-compose-a-practical-guide-to-multi-container-applications-c76811010131)]
|
|
- **`docker compose build`:** If your compose files use the `build:` block to compile local Dockerfiles instead of just pulling pre-made images, this step ensures your Dockerfiles successfully build without crashing.
|
|
|
|
⚠️ Crucial Homelab Gotchas to Keep in Mind
|
|
|
|
1. **Environment Variables (`.env`):** If your `docker-compose.yml` relies on an external `.env` file containing local paths, secret tokens, or personal domain names, `docker compose config` will fail in Gitea Actions because that file is missing. You should either add a `.env.example` file to your Git repository and rename it during the workflow run, or map those variables into **Gitea Secrets**.
|
|
2. **Local Volume Paths:** If your compose files map to absolute local storage paths (e.g., `/mnt/user/appdata/nginx`), the Gitea Act Runner environment won't have access to those actual directories. For testing purposes, it is safest to use relative paths (e.g., `./nginx/config`) or let Docker generate named volumes during the validation phase.
|
|
3. **Runner Capabilities:** Ensure that your local `act_runner` setup has access to a Docker daemon. If you installed your runner using Docker-in-Docker (DinD), it will easily execute the `docker compose` commands embedded in this workflow. [[1](https://versich.com/blog/a-practical-guide-to-building-docker-image-in-gitlab/)]
|