{"id":26116947,"url":"https://github.com/jiwidi/homelab","last_synced_at":"2025-10-13T21:05:41.067Z","repository":{"id":280892404,"uuid":"940685157","full_name":"jiwidi/homelab","owner":"jiwidi","description":"Homelab setup running on an m4 Mac mini","archived":false,"fork":false,"pushed_at":"2025-03-01T20:49:28.000Z","size":15,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-05T22:05:29.191Z","etag":null,"topics":["homelab","macmini","macos","self-hosted","selfhosted"],"latest_commit_sha":null,"homepage":"","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/jiwidi.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}},"created_at":"2025-02-28T15:59:30.000Z","updated_at":"2025-03-03T11:23:04.000Z","dependencies_parsed_at":"2025-03-05T22:05:32.074Z","dependency_job_id":"b38f782f-1f69-4a36-a61a-3f79ebe3c8de","html_url":"https://github.com/jiwidi/homelab","commit_stats":null,"previous_names":["jiwidi/homelab"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiwidi%2Fhomelab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiwidi%2Fhomelab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiwidi%2Fhomelab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiwidi%2Fhomelab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jiwidi","download_url":"https://codeload.github.com/jiwidi/homelab/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242838580,"owners_count":20193526,"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":["homelab","macmini","macos","self-hosted","selfhosted"],"created_at":"2025-03-10T10:53:22.968Z","updated_at":"2025-10-13T21:05:41.060Z","avatar_url":"https://github.com/jiwidi.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏠 My Personal Homelab\n\nThis repository contains the Docker configurations and installation scripts that power my personal homelab server. I've decided to share my setup publicly in case others find it useful for their own homelab projects.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## 💻 Hardware\n\nMy current homelab runs on:\n- **Mac Mini M4**\n- **CPU**: Apple M4 chipset\n- **RAM**: 32GB\n- **Storage**: [2TB custom Chinese NVMe](https://item.taobao.com/item.htm?abbucket=14\u0026id=874377707144\u0026ns=1\u0026priceTId=2100c80417368883046408893e0be2\u0026skuId=5882661866398\u0026spm=a21n57.1.hoverItem.2\u0026utparam=%7B%22aplus_abtest%22%3A%22741a06251058619e3d5eda8db6a4078b%22%7D\u0026xxc=taobaoSearch) replaced the internal 256GB SSD. Video\n\nThe entire setup is compact, energy-efficient, and powerful enough to run all my services simultaneously without breaking a sweat. All while being silent and having a small size footprint.\n\n## 🧩 Services\n\nHere's what's currently running in my homelab:\n\n| Service | Description | Port | URL |\n|---------|-------------|------|-----|\n| **Homepage** | Main dashboard for all services | 3000 | http://localhost:3000 |\n| **Dockge** | Docker Compose stack management | 5001 | http://localhost:5001 |\n| **Cloudflare Tunnel** | Secure remote access | N/A | Various subdomains |\n| **Tailscale** | VPN for secure remote access | N/A | Via Tailscale client |\n| **Glances** | System monitoring | 61208 | http://localhost:61208 |\n| **Transmission** | Torrent client | 9091 | http://localhost:9091 |\n| **Plex** | Media server | Host networking | http://localhost:32400/web |\n| **Excalidraw** | Collaborative drawing tool | 3030 | http://localhost:3030 |\n| **Ollama + OpenWebUI** | Self-hosted AI/LLM service | 8083 | http://localhost:8083 |\n| **Speedtest Tracker** | Internet speed monitoring | 8081 | http://localhost:8081 |\n| **Vert** |  | 3002 | http://localhost:3002 | (Build from source)\n\n## 🚀 Installation\n\n### Prerequisites\n\n- macOS system (the script uses Homebrew for dependencies)\n- Internet connection\n- If you want to replicate my exact setup: a Mac with Apple Silicon\n\n### Setup Process\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/jiwidi/homelab-server.git\n   cd homelab-server\n   ```\n\n2. Run the master installation script:\n   ```bash\n   ./master_install.sh\n   ```\n\n3. Follow the interactive prompts to configure your environment.\n\n## 🔧 Script Explanation\n\n### `master_install.sh`\n\nThis is the main orchestration script that:\n\n1. **Checks and installs dependencies** (Homebrew, Docker, tmux)\n2. **Manages configuration** through a `.env` file\n3. **Sets up all services** by iterating through each directory and running individual installation scripts\n\nThe script is designed to be idempotent - you can run it multiple times without issues. It will only install dependencies if they're missing and will respect existing configurations.\n\n### Service-specific scripts\n\nEach service directory contains:\n- `docker-compose.yaml` - Container configuration\n- `install.sh` - Service-specific installation script\n\nThese modular scripts allow for easier maintenance and give you the flexibility to add or remove services.\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nI use a `.env` file for all sensitive configuration to avoid hardcoding secrets in the repository. The master install script will create this file if it doesn't exist, prompting you for values or generating secure defaults.\n\nKey variables include:\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `CLOUDFLARE_TUNNEL_TOKEN` | Token for Cloudflare Tunnel | (user provided) |\n| `HOMEPAGE_AUTH_TOKEN` | Homepage dashboard auth token | (randomly generated) |\n| `SPEEDTEST_APP_KEY` | Speedtest app auth key | (randomly generated) |\n| `PLEX_CLAIM` | Plex claim token | (user provided) |\n| `TAILSCALE_AUTH_KEY` | Tailscale authentication key | (user provided) |\n\nA `.env.example` file is included as a reference.\n\n## 🔒 Security\n\nSecurity was a priority when designing this setup:\n\n- **No hardcoded secrets** - All sensitive information lives in the `.env` file (excluded from git)\n- **Minimal permissions** - Docker containers run with the minimum required access\n- **Safe Docker socket access** - Socket is exposed securely to prevent unauthorized container access\n- **Automatic secret generation** - The script can generate secure random tokens for services\n- **VPN Access** - Tailscale provides secure access without exposing services directly to the internet\n\n## 📁 Project Structure\n\n```\nhomelab-server/\n├── .env                  # Your environment variables (not committed)\n├── .env.example          # Example environment variables\n├── .gitignore            # Git ignore file (includes .env)\n├── LICENSE               # MIT License\n├── README.md             # This file\n├── master_install.sh     # Main installation script\n│\n├── cloudfare/            # Cloudflare tunnel configuration\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n├── excalidraw/           # Excalidraw drawing tool\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n├── homepage/             # Homepage dashboard\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n├── ollama_openwbui/      # Ollama and OpenWebUI\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n├── plex/                 # Plex media server\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n├── dockge/               # Dockge Compose stack management\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n├── transmission/         # Transmission torrent client\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n├── vert/                 # Vert service\n│   ├── docker-compose.yaml\n│   └── install.sh\n│\n└── tailscale/            # Tailscale VPN for remote access\n    ├── docker-compose.yaml\n    ├── install.sh\n    └── README.md         # Tailscale-specific documentation\n```\n\n## 🧰 Expandability\n\nOne of the key design principles of this setup is easy expandability:\n\n### Adding a New Service\n\n1. Create a new directory for your service\n2. Add a `docker-compose.yaml` file\n3. Create an `install.sh` script (see existing ones as examples)\n4. Update the main `.env` file if your service needs additional environment variables\n\nExample `install.sh` template:\n```bash\n#!/bin/bash\nset -e\nDIR=\"$(cd \"$(dirname \"$0\")\" \u0026\u0026 pwd)\"\ndocker compose --file \"$DIR/docker-compose.yaml\" up -d\n```\n\n### Personal Customizations\n\nI've made several customizations for my specific needs:\n\n- **Media Management**: Plex is configured to use my `~/Videos` directory for media\n- **Swedish Timezone**: Services are configured for Europe/Stockholm timezone\n- **Cloudflare Tunnels**: Set up for my domain (jiwidi.com) and subdomains\n\nFeel free to adjust these settings in the docker compose files to match your requirements.\n\n## 🌐 Remote Access\n\nI provide two options for remote access to my homelab:\n\n### Cloudflare Tunnels\n\nFor public-facing services, I use Cloudflare Tunnels on the free tier. This allows me to expose specific services through a secure tunnel without opening ports on my router.\n\nTo use this feature with your own domain:\n1. Create a Cloudflare account\n2. Set up a tunnel for your domain\n3. Update the `CLOUDFLARE_TUNNEL_TOKEN` in your `.env` file\n\n### Tailscale VPN\n\nFor more secure, private access to all services, I use Tailscale. This mesh VPN allows me to connect to my homelab from anywhere without exposing services directly to the internet.\n\nKey features:\n- **Zero configuration** networking - no port forwarding needed\n- **End-to-end encryption** for all traffic\n- **Access control** through Tailscale's admin console\n- **Exit node capability** - route all your internet traffic through your home connection when on public WiFi\n\nSetup:\n1. Create a Tailscale account at [https://tailscale.com/](https://tailscale.com/)\n2. Generate an auth key in the admin console\n3. Add the key to your `.env` file as `TAILSCALE_AUTH_KEY`\n4. Run the installation script\n\nOnce set up, you can connect to your homelab services using the Tailscale IP address from any device with the Tailscale client installed.\n\n## 🤖 Development Notes\n\nThis is an ongoing project, and I'm continually refining and adding services. Some things I'm considering for the future:\n\n- Home automation integration\n- NAS functionality with an external 4 NVMe drive enclosure\n- Enhanced backup solutions\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiwidi%2Fhomelab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiwidi%2Fhomelab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiwidi%2Fhomelab/lists"}