{"id":17838128,"url":"https://github.com/kozii-d/home-server","last_synced_at":"2026-03-16T09:31:49.435Z","repository":{"id":259608842,"uuid":"767718560","full_name":"kozii-d/home-server","owner":"kozii-d","description":"This is config for my self-hosted services","archived":false,"fork":false,"pushed_at":"2024-10-26T19:53:23.000Z","size":239,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T11:11:16.078Z","etag":null,"topics":["docker","docker-compose","homarr","minecraft","pi-hole","pihole","portainer","raspberry-pi","traefik","wireguard"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kozii-d.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-03-05T19:21:58.000Z","updated_at":"2024-11-22T00:11:24.000Z","dependencies_parsed_at":"2024-10-26T21:55:27.089Z","dependency_job_id":"1ae13816-65c6-444e-9de7-0f341069b323","html_url":"https://github.com/kozii-d/home-server","commit_stats":null,"previous_names":["kozii-d/home-server"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kozii-d%2Fhome-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kozii-d%2Fhome-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kozii-d%2Fhome-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kozii-d%2Fhome-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kozii-d","download_url":"https://codeload.github.com/kozii-d/home-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244515571,"owners_count":20464913,"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":["docker","docker-compose","homarr","minecraft","pi-hole","pihole","portainer","raspberry-pi","traefik","wireguard"],"created_at":"2024-10-27T20:52:04.939Z","updated_at":"2026-03-16T09:31:49.429Z","avatar_url":"https://github.com/kozii-d.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Home Server with Traefik Proxy\n\nWelcome to my home server configuration!\n\nThis configuration will assist you in setting up your own home server using Traefik as a reverse proxy and docker-compose to manage your services. With Traefik, you can effortlessly manage routing, load balancing, and SSL/TLS termination for your web services.\n## System Requirements\n\nBefore you begin, ensure that your system meets the following requirements:\n\n- **Docker:** Ensure Docker is installed on your system. If not, download it from [Docker's official website](https://www.docker.com/get-started/).\n- **apache2-utils**: Make sure apache2-utils is installed on your system. If not, execute the following command in your terminal:\n    ```bash\n    sudo apt update\n    sudo apt install apache2-utils\n    ```\n- **Make:** Make sure you have Make installed on your system. Make is typically available on Unix-like operating systems. If Make is not installed, you can install it using the following command:\n    ```bash\n    sudo apt update\n    sudo apt install make\n    ```\n\n\n## Getting Started\n\nFollow these steps to get started with your Traefik Home Server:\n\n### Clone Repository \n\n### Create .env file\nCopy the `.env.example` file and rename it to `.env`. Execute the following command in your terminal:\n      ```\n      cp .env.example .env\n      ```\n### Traefik with internal services without \"Your connection is not private\" warning\n\nTo use Traefik with internal (local) services without browser security warnings, you need to set up local trusted certificates. Follow these steps:\n\n#### 1. Set the LOCAL_DOMAIN environment variable in your `.env` file:\n`LOCAL_DOMAIN=your-local-domain.local`\n\nThis domain will be used for all your internal services.\n\n#### 2. Generate local certificates by running the following command:\n  ```bash\n    make localCerts\n  ```\n\nThis command will:\n\n- Build and run a Docker container that generates trusted SSL certificates for your local domain.\n- Create certificates for both your main domain and wildcard subdomains (*.your-local-domain.local).\n- Save certificates in the `traefik/localCerts` directory.\n- Create a TLS configuration file in `traefik/dynamic/local-tls.yml`.\n- Display instructions for installing the root certificate on your client devices.\n\n#### 3. Install the root certificate on your client devices\n**On macOS:**\n  ```bash\n    # First, copy the certificate from your server (if needed)\n    scp username@server-ip:~/server/traefik/localCerts/rootCA.pem ~/Downloads/\n    \n    # Install the certificate\n    sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/Downloads/rootCA.pem\n  ```\n**On Windows:**\n- Copy the `rootCA.pem` file to your Windows machine\n- Rename it to `rootCA.crt` if Windows cannot recognize the file type\n- Double-click the file to open the certificate installer\n- Select \"Local Machine\" and click \"Next\"\n- Choose \"Place all certificates in the following store\"\n- Select \"Trusted Root Certification Authorities\"\n- Complete the installation\n\n#### 4. Restart your browser to apply the changes.\n\nAfter completing these steps, you can access your local services using HTTPS (https://service.your-local-domain.local) without any security warnings in your browser.\n\n**Note:** If you add new devices to your network, you'll need to install the root certificate on them as well to avoid security warnings\n\n\n### Traefik with external services and Let's Encrypt\n\nTo enable external services and obtain SSL/TLS certificates from Let's Encrypt, you need to perform the following steps:\n\n**You need to set the environment variables in the `.env` file:**\n- `EXTERNAL_DOMAIN` - the domain name that will be used to access external services.\n- `ROOT_EMAIL` - the email address that will be used for registering Let's Encrypt certificates.\n\n**Also, to obtain SSL/TLS certificates, you need to choose and configure a challenge**\n\n***DNS Challenge***\n\nIf you use Cloudflare as your DNS provider, then I recommend using the DNS challenge to obtain certificates. To do this, you need to set the following environment variables in the `.env` file:\n- `CLOUDFLARE_EMAIL` - the email address used to log into Cloudflare.\n- `CLOUDFLARE_DNS_API_TOKEN` - the API key that can be created on your Cloudflare profile page.\n\nIf you use another DNS provider, you can check its support in the [official Traefik documentation](https://doc.traefik.io/traefik/https/acme/#providers).\n\nIf your provider is not supported, you will have to use the HTTP challenge.\n\n***HTTP Challenge***\n\nTo use the HTTP challenge, you need to uncomment the lines configuring the `HTTP Challenge` in the `traefik/docker-compose.traefik.yml` file and comment out the lines configuring the `DNS Challenge`.\n\nAlso, for the HTTP challenge, you need to have port 80 open on your router. More about this below.\n\n\n\u003e **Warning!** To enable staging for Let's Encrypt to avoid hitting rate limits, uncomment the line with the `caServer` setting in the `traefik/docker-compose.traefik.yml` file. When you're ready to obtain real certificates, remember to comment out or remove this line.\n\n### Configure Traefik dashboard\n\n- To add authentication to Traefik dashboard, generate a password hash for the user by executing the following command in your terminal:\n  ```\n  echo $(htpasswd -nb \"\u003cUSER\u003e\" \"\u003cPASSWORD\u003e\") | sed -e s/\\\\$/\\\\$\\\\$/g\n  ```\n- Copy the username and the generated hash and paste them into the `TRAEFIK_USER` and `TRAEFIK_HASHED_PASSWORD` variables in the `.env` file.\n\n### External and internal services\n\nIn this configuration, there is a separation between external and internal services. External services are accessible from the Internet, and internal ones only from the local network.\n\nTo separate internal and external services, 4 entry points were created:\n- `web` -  entry point for internal services that are only accessible from the local network. **Port 80.**\n- `websecure` -  entry point for internal services that are only accessible from the local network over HTTPS. **Port 443.**\n- `web-external` - entry point for external services that are accessible from the internet. **Port 81.**\n- `websecure-external` - entry point for external services that are accessible from the internet over HTTPS. **Port 444.**\n\n### Port Forwarding\n\nTo enable external services, you need to set up port forwarding on your router. Port forwarding should be configured as follows:\n- Port `81` -\u003e Port `80` of your server\n- Port `444` -\u003e Port `443` of your server\n\nAlso, you need to set up port forwarding for external services that will use ports different from HTTP and HTTPS.\n\nFor example, WireGuard uses port 51820 and UDP protocol; to make it work, you need to set up port forwarding:\n- Port `51820` -\u003e Port `51820` of your server\n\nMinecraft server uses port 25565 and TCP protocol; to make it work, you need to set up port forwarding:\n- Port `25565` -\u003e Port `25565` of your server\n\n![Port Forwarding](images/portForwarding.png)\n\n## Pi-Hole\nIn this configuration, Pi-Hole is used as a local DNS server and ad blocker.\n\nTo use Pi-Hole, you need to set up your server as the DNS server on your router.\n1. Log into your router's admin panel.\n2. Go to DHCP Server settings.\n3. Reserve an IP address for your server so it does not change in the future.\n4. Set the IP address of your server as the primary DNS server. Leave the secondary and tertiary DNS servers empty.\n5. Save the settings and reboot the router.\n\n![DHCP Server Config](images/dhcpConfig.png)\n\nAlso, it's important to configure local domains in Pi-Hole. To do this, you can use the Pi-Hole admin panel and go to the `Local DNS` tab.\n\nBut the most convenient way is to create a wildcard entry for your local domain, so you don't have to add each subdomain manually.\n\nTo do this, create a file `02-my-wildcard-dns.conf` in the directory `./pihole/etc-dnsmasq.d/` and add the following entry:\n```\naddress=/mydomain.local/192.168.0.95\n```\nWhere `mydomain.local` is your local domain, and `192.168.0.95` is the IP address of your server.\n\n## WireGuard\nWireGuard is a fast and modern VPN protocol that provides secure connection to your home server from anywhere in the world.\n\nBy connecting to your server via WireGuard, you get access to the local network and internal services from anywhere in the world.\n\nMoreover, on a device connected to WireGuard, there will be no ads even over LTE :)\n\nYou can set up peers that will be created initially in the file `./wireguard/docker-compose.wireguard.yml` by changing the environment variables `PEERS`.\nYou can also add new peers via the console inside the `wireguard` docker container.\n\nConnection data for WireGuard can be found in the file `./wireguard/config/peer_name`.\n\nRemember to create a DNS record with the subdomain `wg` for your WireGuard server, so you can connect to it by domain name.\n\n\u003e **Warning!** If you use Cloudflare as your DNS provider, DO NOT use Cloudflare DNS Proxy for the subdomain `wg`, as WireGuard does not work through a proxy.\n\n### DNS Configuration\n\nAdd DNS records for the subdomains that will be used to access the external services. For example, if you want to use the subdomain \"api\", add a DNS record for this subdomain on your DNS provider's website. After that, modify the subdomain in the `docker-compose.servicename.yml` file.\n\n### Utilize Makefile\n\nUtilize the provided Makefile for streamlined command execution. Run `make help` in your terminal to view a list of available commands along with their descriptions.\n\n## Adding Services\n\nTo add a new service to your Traefik setup, follow these guidelines:\n\n**For Docker-based Services:**\n\nCreate a separate directory for each service following this structure:\n```plaintext\n    service/\n    ├── conf\n    │   └── ...\n    ├── data\n    │   └── ...\n    ├── docker-compose.servicename.yml\n    ├── logs\n    │   └── ...\n    └── README.md\n```\n\nBy following this structure, you can easily manage and scale your services within Traefik. Each service will have its own `docker-compose.servicename.yml` file, which will be used to define the service's configuration.\nDon't forget to add the service to the base `docker-compose.yml` file in the root directory of this repository.\n\n**For Non-Docker Services:**\n\nIf you want to add a service that doesn't use Docker, you can still integrate it with Traefik by adding its dynamic configuration YAML files to the `traefik/dynamic` directory. Traefik will automatically detect and configure these services based on the provided configuration files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkozii-d%2Fhome-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkozii-d%2Fhome-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkozii-d%2Fhome-server/lists"}