HomelabOS

Your very own offline-first privacy-centric open-source data-center! https://homelabos.com/

Overview

Your very own offline-first open-source data-center! Includes over 50 services!

Detected project types: Python, Ruby, Docker, Make-based, Documentation.

At a glance

• Default branch: dev
• Visibility: public
• Size: 9.2 MB
• Created: 2026-04-27
• Last updated: 2026-04-27
• Stars / Forks / Open issues: 0 / 0 / 0
• License: MIT

Languages

Language	Bytes	Share
Jinja	290,501 bytes	69.8%
CSS	52,531 bytes	12.6%
PHP	26,799 bytes	6.4%
HTML	13,602 bytes	3.3%
Makefile	8,766 bytes	2.1%
Go	6,182 bytes	1.5%
Ruby	5,502 bytes	1.3%
Python	4,520 bytes	1.1%
Shell	4,462 bytes	1.1%
Dockerfile	2,124 bytes	0.5%
JavaScript	1,149 bytes	0.3%

Repository structure

• .gitlab/
• bin/
• docs/
• group_vars/
• host_vars/
• package_template/
• roles/
• src/
• static/
• website/
• .gitignore (189 B)
• .gitlab-ci.yml (755 B)
• .yamllint (593 B)
• CHANGELOG.md (5,911 B)
• check_version.sh (625 B)
• config.yml.blank (62 B)
• config_inventory (22 B)
• docker_helper.sh (212 B)
• Dockerfile (2,124 B)
• Gemfile (167 B)
• Gemfile.lock (653 B)
• get_setting.sh (111 B)
• git_sync.sh (261 B)
• homelaboslogo.txt (5,969 B)
• install_homelabos.sh (2,283 B)
• LICENSE (1,067 B)
• Makefile (8,766 B)
• mkdocs.yml (3,058 B)
• MOTD (209 B)
• Pipfile (171 B)
• Pipfile.lock (7,618 B)
• playbook.config.yml (1,049 B)
• playbook.homelabos.yml (1,197 B)
• playbook.remove.yml (245 B)
• playbook.restart.yml (107 B)
• playbook.terraform.yml (192 B)
• README.md (11,192 B)
• restore.yml (160 B)
• set_setting.sh (317 B)
• set_vault_pass.sh (112 B)
• terraform.sh (541 B)
• test_hosts (23 B)
• test_inventory (46 B)
• Vagrantfile (816 B)
• VERSION (5 B)
• yamllint.conf (163 B)

Getting started

Clone the repository:

git clone https://forgejo.deployview.com/ssa/HomelabOS.git
cd HomelabOS

Installation

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

bundle install

docker build -t image-name .
docker run --rm -it image-name
# or with compose
docker compose up -d

make

Usage

Invoke the main entry point:

python3 main.py    # or the appropriate module

After building, run the container with the command shown above. Mount volumes and forward ports as required by the application.

Original README

The content below is preserved from the previous README. Headings have been demoted so they don't compete with the new top-level sections.

Your very own offline-first open-source data-center! Includes over 50 services!

Beta Software Warning

This software has not reached version 1.0 and should therefore be considered unstable. While any tagged version should work well on its own, a nice friendly upgrade path from one version to another is not guaranteed.

If you like getting your hands dirty in early versions of software, this is for you. If you prefer to wait till things are stable and friendly, maybe hold off for a while.

Also, if you trash your server or wreck your data, that's on you. Test your backups. Trust nothing.

Documentation

Installation

Summary

A set of Ansible scripts to configure a Docker based Homelab server with all sorts of goodies. Following the unix philosophy we gather together many specific tools to build the exact end result desired.

Goals

To make it easy for anyone to own all their data in an easy and secure way, without the need of cloud providers.

Features

• One command deployment bash <(curl -s https://gitlab.com/NickBusey/HomelabOS/-/raw/dev/install_homelabos.sh)
• Manual deployment - Installation
• Automated Backups
• Easy Restore
• Automated Tor Onion Service access
• Automated HTTPS via LetsEncrypt
• Automated Settings Sync
• OpenVPN
• OpenLDAP
• Cloud Bastion Server with WireGuard VPN

Planned Features

Installation Tutorial / Demo

Local Demo

If you have the latest version of Vagrant and Virtual Box setup you can demo things locally by running make develop. This will spin up a temporary developer copy on your local computer without needing an actual server to point things at. Note no data will actually be saved from inside the VM, so this is for testing only.

Available Software

• Airsonic - Airsonic is a free, web-based media streamer, providing ubiquitous access to your music.
• Apache - Web server
• Authelia - Authelia is an open-source full-featured authentication server available on Github
• Beets - Beets is the media library management system for obsessive-compulsive music geeks.
• Bitwarden - Password and secrets manager via bitwarden-rs
• BookStack - Simple & Free Wiki Software
• BulletNotes - Note taking application
• Calibre - Complete ebook library management.
• Code-Server - Run VS Code on a remote server.
• Darksky - Local weather reported via darksky-influxdb
• Dasher - Amazon Dash button support
• Digikam - Professional Photo Management with the Power of Open Source
• Documentation - Offline, searchable documentation via MkDocs
• Drone - Drone is a self-service continuous delivery platform
• Emby - Personal Media Server
• Firefly III - Money management budgeting app
• FreshRSS - A free, self-hostable aggregator
• Ghost - Ghost is a platform for building and running a modern online publication
• Gitea - Git hosting
• Grafana - Pretty graphs
• Guacamole - a clientless remote desktop gateway
• HealthChecks - A Cron Monitoring Tool written in Python & Django https://healthchecks.io
• Home Assistant - Home Automation
• HomeBridge - HomeKit support for the impatient
• Homedash - Dashboard
• InfluxDB - Time series data storage
• Inventario - Home inventory management
• Jackett - API Support for your favorite torrent trackers (helps Sonarr and Radarr)
• Jellyfin - The Free Software Media System
• Kibitzr - IFTTT replacement
• Lidarr - Sonarr but for Music.
• MStream - All your music, everywhere you go.
• Mailserver - Fully featured mail server
• Mailu - is a simple yet full-featured mail server as a set of Docker images.
• Mashio - Home brewery management software
• Matomo - Web analytics
• Mayan EDMS - Free Open Source DMS (document management system).
• Minio - S3 hosting
• Miniflux - Miniflux is a minimalist and opinionated feed reader.
• Monica - Contact / relationship manager
• Mylar - An automated Comic Book manager
• NetData - Monitor your systems and applications, the right way!
• NextCloud - Private Cloud Storage, Calendar, Contacts, etc.
• Ombi - Ombi is a self-hosted web application that automatically gives your shared Plex or Emby users the ability to request content by themselves!
• Organizr - Access all your HomelabOS services in one easy place.
• OwnPhotos Self hosted Google Photos clone.
• Paperless - Document management
• PhpLDAPadmin - LDAP management interface
• Pi-hole - Ad blocking
• Piwigo - Manage your photo collection
• Pixelfed - A free and ethical photo sharing platform, powered by ActivityPub federation.
• Plex - Personal Media Server
• Poli - An easy-to-use BI server built for SQL lovers. Power data analysis in SQL and gain faster business insights.
• Portainer - Easy Docker management
• Radarr - Automated movie downloading
• Searx - A privacy-respecting, hackable metasearch engine.
• SickChill - SickChill is an automatic Video Library Manager for TV Shows.
• Sonarr - Automated TV downloading
• Speedtest - A tool to run periodic speedtests and save them in InfluxDB for graphing in Grafana
• Syncthing - File syncing software
• Tautulli - Monitor your Plex Server
• Telegraf - Server statistics reporting
• The Lounge - Always-on IRC client (IRC bouncer)
• Transmission - BitTorrent client
• Trilium - Build your personal knowledge base with Trilium Notes
• Ubooquity - Ubooquity is a free home server for your comics and ebooks library
• Wallabag - Save and classify articles. Read them later. Freely.
• Watchtower - A process for automating Docker container base image updates
• WebVirtMg is a complete Kernel Virtual Machine (KVM) hypervisor manager.
• Wekan - Open source Kanban board with MIT license
• Zulip - Threaded chat software

Requirements

A server with:

• Ubuntu 18.04 or Debian 10.3
• Passwordless SSH via SSH keys working.

Another computer with:

• Docker

Note: Two separate computers are not required, but are highly recommended. The idea is you have a server and then your personal computer, say a laptop or desktop. You deploy from your personal computer to the server. This way your settings are saved on your personal computer, and can be used to re-build the server and restore from backups if anything goes wrong.

Optional Items

Domain Name

A domain configured with a A type DNS record of *.yourdomain.com pointed at your server's IP address. (This is optional because you can use Tor to access your services without registering a domain. For best support from 3rd party clients an actual domain is highly recommended. Also certain services do not work through TOR at the moment.) Note you can hang this off a subdomain as well, so *.homelab.yourdomain.com will work as well.

Port Forwarding

Ports 80 and 443 punched through any firewalls and port forwarded at your server in question. (This is also optional due to Tor access, but again highly recommended.)

Cloud Bastion Server

Rather than pointing the domain at your home IP and having to manage DDNS, you can utilize a cloud server to act as a bastion host via Tinc vpn and nginx.

S3 Account

S3 is Amazon's Simple Storage Service which HomelabOS can optionally use to back up to. You can use Amazon's service, or one of many other S3 compatible providers. You can also back up to another HomelabOS instance if that other instance is running Minio, a self-hosted S3 service.

Installation

Roadmap

• Actual OS bundle with everything pre-configured
• Web interface to enable/disable services

Alternatives

• Ansible NAS
• DockSTARTer

Get Support

• File an issue
• Ask a question on Reddit
• Threaded support and development discussion on Zulip

Give Support

Become a Supporter on Patreon

Contributing

Watch Live Development

You can watch live development of this project on Nick Busey's Twitch Stream.

Contributing

Contributions are welcome. The typical workflow is:

1. Open an issue describing the change you'd like to make.
2. Fork the repository (or create a feature branch if you have write access).
3. Commit your changes with clear, descriptive messages.
4. Open a pull request against the dev branch.

Please follow the existing code style and include tests or reproduction steps where relevant.

License

This project is licensed under the MIT license. See the LICENSE file for the full text.

Repository

• Browse: https://forgejo.deployview.com/ssa/HomelabOS
• Clone (HTTPS): https://forgejo.deployview.com/ssa/HomelabOS.git
• Clone (SSH): ssh://git@forgejo.deployview.com:30143/ssa/HomelabOS.git

---

This README was generated automatically based on repository metadata, contents, and any prior README content. Edit any section above to add project-specific detail.