{"id":15083549,"url":"https://github.com/tmorin/homecloud-ansible","last_synced_at":"2025-10-05T14:31:18.685Z","repository":{"id":42140115,"uuid":"297574074","full_name":"tmorin/homecloud-ansible","owner":"tmorin","description":"homecloud provides a ready-to-use set of resources to bootstrap a cloud at home mainly based on Kubernetes and Syncthing.","archived":true,"fork":false,"pushed_at":"2023-07-11T17:37:32.000Z","size":4987,"stargazers_count":30,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-09-26T06:01:36.472Z","etag":null,"topics":["ansible","ansible-galaxy","ansible-playbook","ansible-roles","docker","docker-swarm","docker-swarm-stacks"],"latest_commit_sha":null,"homepage":"https://galaxy.ansible.com/tmorin/homecloud","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmorin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":"thibault.morin","issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-09-22T07:45:39.000Z","updated_at":"2023-12-30T01:19:07.000Z","dependencies_parsed_at":"2023-01-19T15:47:43.446Z","dependency_job_id":null,"html_url":"https://github.com/tmorin/homecloud-ansible","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmorin%2Fhomecloud-ansible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmorin%2Fhomecloud-ansible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmorin%2Fhomecloud-ansible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmorin%2Fhomecloud-ansible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmorin","download_url":"https://codeload.github.com/tmorin/homecloud-ansible/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219877015,"owners_count":16554817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-galaxy","ansible-playbook","ansible-roles","docker","docker-swarm","docker-swarm-stacks"],"created_at":"2024-09-25T06:02:02.539Z","updated_at":"2025-10-05T14:31:18.254Z","avatar_url":"https://github.com/tmorin.png","language":"Shell","funding_links":["https://liberapay.com/thibault.morin"],"categories":[],"sub_categories":[],"readme":"# homecloud-ansible\n\n[![badge for Ansible Collection](https://img.shields.io/badge/Ansible%20Collection-tmorin/homecloud-blue?logo=ansible\u0026logoColor=white)](https://galaxy.ansible.com/tmorin/homecloud)\n[![badge for HTML paper](https://img.shields.io/badge/Paper-HTML-informational)](https://tmorin.github.io/homecloud-ansible)\n[![badge for PDF paper](https://img.shields.io/badge/Paper-PDF-informational)](https://tmorin.github.io/homecloud-ansible/homecloud-paper.pdf)\n\n[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/tmorin/homecloud-ansible/Continous%20Integration/master?label=GitHub%20Actions\u0026logo=github+actions\u0026logoColor=black)](https://github.com/tmorin/homecloud-ansible/actions?query=workflow%3A%22Continous+Integration%22+branch%3Amaster)\n\n[comment]: \u003c\u003e ([![Travis \u0026#40;.org\u0026#41; branch]\u0026#40;https://img.shields.io/travis/tmorin/homecloud-ansible/master?label=Travis%20CI\u0026logo=travis+CI\u0026logoColor=black\u0026#41;]\u0026#40;https://travis-ci.org/github/tmorin/homecloud-ansible\u0026#41;)\n\n\u003e `homecloud` provides a ready-to-use set of resources to bootstrap a cloud at home mainly based on Kubernetes and Syncthing.\n\nThis is the **version 2** of the library.\n\nThe **version 1** of the library is available in the **v1.x branch**.\n\n## Presentation\n\n`homecloud` aims to provide a cloud like environment, especially an internal cloud, at home.\nThe underlying infrastructure is primarily based on low cost ARM boards, like Raspberry Pi, and powered by open source solutions like Kubernetes or Syncthing.\n\nThe main artifact is an Ansible collection designed to bootstrap a ready to use cloud like environment as well as a couple of end-users services.\n\nAn in-depth explanation is available in the [paper](./paper/README.adoc).\n\n## Overview\n\nThe Ansible collection provides the following features:\n\n- a `Kubernetes` cluster\n- a modern reverse proxy for UDP, TCP and HTTP handled by `Traefik`\n- a distributed block storage system handled by `Longhorn`\n- the native Kubernetes dashboard\n- a support of high availability handled by `Keepalived`\n- a decentralized solution to synchronize files between local/remote nodes, `dnas`, powered with `Syncthing`, `NFS` and `Samba`\n\nAdditionally, Armbian images can be created for each host of the inventory.\n\nFinally, once `homecloud` is bootstrapped, then end-user applications can be deployed on the `Kubernetes` cluster.\nSome of them are available as `Kustomize` resources in another repository [tmorin/homecloud-kustomize](https://github.com/tmorin/homecloud-kustomize).\n\n## Requirements\n\nEach hosts must fulfill the following constraints:\n\n- Operating System: Ubuntu (18.04, 20.04) and Debian (Stretch, Buster)\n- CPU Architecture: amd64 or arm64\n- Memory: at least 2Go\n\nWhen `longhorn` is enabled, the data are stored a block device, i.e. `/dev/???`.\nThe collection handles the preparation of two kinds of block devices: \nthe hardware component like a Sd-Card or a Loop Device based on a `.img` file.\n\nWhen `dnas` is enabled, the data are stored a block device, i.e. `/dev/???`.\nThe collection handles the preparation of only block devices based on a hardware component like a Sd-Card, USB disk ...\n\n## Dependencies\n\nIn order to build the custom Armbian images, additional dependencies are required:\n```shell script\napt-get install jq qemu-system-arm qemu-user-static\n```\n\n## Local environment setup\n\nInstall dependencies for Vagrant and VirtualBox\n```shell\nsudo apt-get install -y vagrant virtualbox virtualbox-ext-pack\nvagrant plugin install vagrant-vbguest\n```\n\nCreate the Python virtual environment\n```shell\nvirtualenv venv\nsource venv/bin/activate\n```\n\nInstall the dependencies\n```shell\npip install -r requirements.txt\n```\n\nThe collection dependencies are bundled in [./molecule/resources/collections.yml](molecule/resources/collections.yml).\n```shell\nansible-galaxy collection install -r molecule/resources/collections.yml\n```\n\nLint the Ansible collection\n```shell\n./lint\n```\n\n## Testing\n\nSeveral cases are tested using [molecule], [vagrant] and the plugin [vagrant-libvirt].\n\n### Tested layouts\n\nThe test suite targets the following operating systems:\n\n- Ubuntu\n- Debian\n\n|               | [k1] | [k1ha] | [k1lo] | [k2] | [k2ha] | [armbian] | [ubuntu_raspi] |\n|---------------|------|--------|--------|------|--------|-----------|----------------|\n| servers       | 1    | 1      | 1      | 1    | 2      | 0         | 0              |\n| agents        | 0    | 0      | 0      | 1    | 0      | 0         | 0              |\n| keepalived    | no   | yes    | no     | yes  | yes    | no        | no             |\n| longhorn      | no   | yes    | yes    | yes  | yes    | no        | no             |\n| traefik       | yes  | yes    | no     | yes  | yes    | no        | no             |\n| dashboard     | yes  | no     | no     | no   | no     | no        | no             |\n| dnas          | yes  | yes    | no     | no   | no     | no        | no             |\n| hardening     | no   | no     | no     | no   | no     | no        | no             |\n| Armbian image | no   | no     | no     | no   | no     | yes       | no             |\n| Ubuntu image  | no   | no     | no     | no   | no     | no        | yes            |\n\nTest the scenario `k1`\n```shell\nsource venv/bin/activate\nmolecule test -s k1\n```\n\nConfigure local (Ansible agent) kubectl for `k1`\n```shell\nexport KUBECONFIG=$HOME/.kube/k1\nkubectl get all --all-namespaces\n```\n\nConfigure local (Ansible agent) kubectl for `k1ha`\n```shell\nexport KUBECONFIG=$HOME/.kube/k1ha\nkubectl get all --all-namespaces\n```\n\nConfigure local (Ansible agent) kubectl for `k2`\n```shell\nexport KUBECONFIG=$HOME/.kube/k2\nkubectl get all --all-namespaces\n```\n\nConfigure local (Ansible agent) kubectl for `k2ha`\n```shell\nexport KUBECONFIG=$HOME/.kube/k2ha\nkubectl get all --all-namespaces\n```\n\n[k1]: molecule/k1\n[k1ha]: molecule/k1ha\n[k1lo]: molecule/k1lo\n[k2]: molecule/k2\n[k2ha]: molecule/k2ha\n[armbian]: molecule/armbian\n[ubuntu_raspi]: molecule/ubuntu_raspi\n[molecule]: https://github.com/ansible-community/molecule\n[vagrant]: https://www.vagrantup.com/\n[vagrant-libvirt]: https://github.com/vagrant-libvirt/vagrant-libvirt\n\n### Tested playbooks\n\nThe test suite plays several playbooks to configure the cluster nodes, to deploy the stacks and to perform restore operations.\n\nThey are located in the molecule directory: [molecule/resources/playbooks](molecule/resources/playbooks).\n\n#### Hardening\n\nPresently, the repository doesn't provide playbooks for OS hardening.\nHowever, an existing initiative may help you to build your own: [devsec.hardening](https://galaxy.ansible.com/devsec/hardening).\n\n#### Bootstrap the cluster\n\nThe playbook [cluster-bootstrap.yml](molecule/resources/playbooks/cluster-bootstrap.yml) bootstraps the cluster, i.e. the Kubernetes cluster and the Decentralized NAS.\n\n#### Deploy the Kubernetes deployment manifests\n\nThe playbook [k3s-deploy.yml](molecule/resources/playbooks/k3s-deploy.yml) deploys the Kubernetes deployment manifests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmorin%2Fhomecloud-ansible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmorin%2Fhomecloud-ansible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmorin%2Fhomecloud-ansible/lists"}