{"id":19011271,"url":"https://github.com/kdkasad/home-server","last_synced_at":"2025-08-26T23:33:48.240Z","repository":{"id":244293341,"uuid":"813927409","full_name":"kdkasad/home-server","owner":"kdkasad","description":"Ansible playbook to deploy \u0026 manage my home server","archived":false,"fork":false,"pushed_at":"2025-08-23T19:19:02.000Z","size":358,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-24T07:29:49.062Z","etag":null,"topics":["ansible","devops","docker","home-server","homelab","nas","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Python","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/kdkasad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-12T02:31:59.000Z","updated_at":"2025-08-23T19:19:05.000Z","dependencies_parsed_at":"2024-07-11T18:27:30.265Z","dependency_job_id":"7e08471d-3bef-49a3-aa3e-85686384afa2","html_url":"https://github.com/kdkasad/home-server","commit_stats":{"total_commits":136,"total_committers":1,"mean_commits":136.0,"dds":0.0,"last_synced_commit":"15f3f98871f278a561d69e45179d91a888789e5d"},"previous_names":["kdkasad/home-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kdkasad/home-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdkasad%2Fhome-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdkasad%2Fhome-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdkasad%2Fhome-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdkasad%2Fhome-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kdkasad","download_url":"https://codeload.github.com/kdkasad/home-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdkasad%2Fhome-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272267230,"owners_count":24903642,"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","status":"online","status_checked_at":"2025-08-26T02:00:07.904Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","devops","docker","home-server","homelab","nas","self-hosted"],"created_at":"2024-11-08T19:13:55.805Z","updated_at":"2025-08-26T23:33:48.205Z","avatar_url":"https://github.com/kdkasad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Home server playbook\n\n[![CI](https://github.com/kdkasad/home-server/actions/workflows/ci.yml/badge.svg)](https://github.com/kdkasad/home-server/actions/workflows/ci.yml)\n\nAn Ansible playbook to manage my home server,\na mini-PC running Debian.\n\nThis playbook is heavily inspired by David Stephens'\n[Ansible NAS](https://ansible-nas.io) project.\nMuch of the structure and some of the roles are taken from there.\n\nAny roles which were adapted from Ansible NAS have their own license files\nin their respective directories to retain the original copyright and license.\n\n## What's included?\n\nThis playbook installs and configures the following services\n(when enabled in `config.yml`):\n\n### User-facing services\n\nThese are services hosted on the server that end users can interact with\ndirectly.\n\n#### Organization\n- [Homarr](https://homarr.dev) web dashboard.\n\n#### Observability \u0026 monitoring\n- [Grafana](https://grafana.com), a data dashboarding tool.\n  Used to display metrics from Prometheus and send alerts based on data.\n- [Prometheus](https://prometheus.io), a monitoring and alerting toolkit.\n  Collects metrics from various sources, and provides them to Grafana for display.\n- [Loki](https://grafana.com/loki), a log aggregation system.\n  Collects logs from various sources, and provides them to Grafana for display.\n\n#### Storage \u0026 file sharing\n- LAN file sharing (for NAS use), using [Samba](https://www.samba.org/)\n  - Zero-configuration network discovery for MacOS, Windows, and Linux clients\n    using [Avahi](https://github.com/avahi/avahi) (mDNS, DNS-SD)\n    and [wsdd2](https://github.com/Netgear/wsdd2) (WS-Discovery, LLMNR).\n- [Jellyfin](https://jellyfin.org) media server. Streams movies, TV shows,\n  music, and more over the web.\n- [MinIO](https://min.io), an S3-compatible object storage server.\n\n#### Infrastructure \u0026 security\n- [Authentik](https://goauthentik.io), a self-hosted identity provider.\n  Acts as a central authentication system for other services.\n- [Tailscale](https://tailscale.com), a VPN service.\n  Allows secure access to the server from anywhere.\n- [Bitwarden](https://bitwarden.com) password manager,\n  using [Vaultwarden](https://github.com/dani-garcia/vaultwarden).\n\n#### Games\n- [Minecraft](https://www.minecraft.net/en-us) server\n  (Java Edition), using [itzg/docker-minecraft-server](https://github.com/itzg/docker-minecraft-server).\n\n### System services\n\nThe server also runs several services that are not directly user-facing, but are\nnecessary nonetheless.\n\n- [Docker](https://docker.io), a containerization platform.\n  Used to run most of the other services as containers.\n- [Traefik](https://traefik.io/traefik/) reverse proxy, for routing traffic to\n  services and managing TLS certificates.\n- [ddclient](https://github.com/ddclient/ddclient), a dynamic DNS client.\n  Updates the server's DNS record with the current public IP address.\n- Local DNS server using [dnsmasq](https://dnsmasq.org/doc.html).\n  Allows for custom DNS records, making the server accessible by the same name\n  from the local network and the rest of the internet.\n- Cron job to ping Healthchecks.io service.\n- Metric/log exporters:\n  - [Prometheus node exporter](https://github.com/prometheus/node_exporter)\n    to export system metrics.\n  - [cAdvisor](https://github.com/google/cadvisor)\n    to export Docker container performance metrics.\n  - [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/),\n    to export system \u0026 Docker container logs to Loki.\n- [Fail2ban](https://github.com/fail2ban/fail2ban), a log-based intrusion\n  prevention system. Monitors logs for authentication failures and blocks\n  IPs that have too many failures.\n\n### Planned\n\nThese are some of the services/features I'd like to add in the near future:\n\n- Automated data backups\n- Automated configuration for using Authentik to provide authentication for services\n\n## Installation\n\nIf you're looking to use this playbook to deploy your own home server, you may\nwant to take a look at [Ansible NAS](https://ansible-nas.io) instead.\nIt's a more complete and polished project, designed for you to customize.\nThis playbook is just for my personal server,\nand while it is designed to be customizable,\nit's not as polished or well-tested as Ansible NAS.\n\nThat being said, follow these steps to deploy a home server with this playbook:\n\n#### 1. Install the latest version of Debian on your server.\n\nI am running Debian 12 (Bookworm), but I plan to keep this playbook up-to-date\nwhen new versions of Debian are released.\n\n##### LVM\n\nThis playbook expects an LVM volume group to be set up.\nBecause that depends on the specific disk configuration of your server,\nyou will need to set that up manually before running this playbook.\nThe playbook uses the name `pool` for the VG, but that can be changed in `config.yml`.\n\n\u003e [!NOTE]\n\u003e If you are using the Debian installer, you can simply select the _Guided - use entire disk and set up LVM_ option.\n\u003e Note the name of the volume group that is created.\n\u003e This can be found by running the `vgs` command in the new system.\n\n##### SSH\n\nSet up **key-based** SSH access for a user with sudo or su privileges.\nThe playbook disables password authentication for SSH.\n\n\u003e [!CAUTION]\n\u003e If you don't have an SSH keypair set up, you will lose SSH access to your server.\n\n#### 2. Install Ansible on your local machine.\n\n#### 3. Clone this repository.\n\n```\n$ git clone https://github.com/kdkasad/home-server.git\n```\n\n#### 4. Install the required dependencies from Ansible Galaxy.\n\n```\n$ ansible-galaxy install -r requirements.yml\n```\n\n#### 5. Configure the `inventory` file to match your server's network address.\n\n```\n$ cp inventory.sample inventory\n```\n\nThen edit `inventory`, replacing the `\u003cplaceholders\u003e` with the proper values for your environment.\n\nI also specify the SSH key to use in the inventory file,\nand I store that key in the `keys/` directory of this repository.\nYou can remove this setting, and Ansible will use the default SSH key search path instead.\n\n#### 6. Use the sample configuration file to create your own configuration file.\n\n```\n$ cp config.yml.sample config.yml\n```\n\nThen edit `config.yml` to meet your needs.\n\n\u003e [!NOTE]\n\u003e This will overwrite the existing `config.yml` file,\n\u003e which contains my personal settings for my server.\n\u003e\n\u003e If you want to keep that file for reference,\n\u003e rename it first:\n\u003e\n\u003e ```\n\u003e $ mv config.yml config-kdkasad.yml\n\u003e ```\n\n#### 7. Simply run the `main.yml` playbook using Ansible.\n\n```\n$ ansible-playbook -K main.yml\n```\n\n#### 8. You're done!\n\nYou can reboot your server to be extra sure all changes are applied,\nbut it shouldn't be necesary.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdkasad%2Fhome-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkdkasad%2Fhome-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdkasad%2Fhome-server/lists"}