{"id":15148288,"url":"https://github.com/simonwep/openvpn-pihole","last_synced_at":"2025-04-07T09:18:41.311Z","repository":{"id":44517965,"uuid":"291279406","full_name":"simonwep/openvpn-pihole","owner":"simonwep","description":"🕵️ A truly delicious combination of two wonderful pieces of software to setup a pi.hole-backed VPN as quick and easy as possible.","archived":false,"fork":false,"pushed_at":"2025-03-26T19:22:33.000Z","size":51,"stargazers_count":75,"open_issues_count":3,"forks_count":22,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T08:08:21.065Z","etag":null,"topics":["containerization","docker","docker-compose","docker-image","openvpn","openvpn-installer","openvpn-server","pihole"],"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/simonwep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":"simonwep","patreon":"simonwep","custom":["paypal.me/simonreinisch","buymeacoffee.com/aVc3krbXQ"]}},"created_at":"2020-08-29T13:46:02.000Z","updated_at":"2025-03-26T19:22:38.000Z","dependencies_parsed_at":"2024-06-02T13:35:01.349Z","dependency_job_id":"e877a652-8d0f-427b-8c0b-ca95d3d4b0cf","html_url":"https://github.com/simonwep/openvpn-pihole","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"a5b4824b8fee844472d472ca525605af05c337b4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fopenvpn-pihole","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fopenvpn-pihole/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fopenvpn-pihole/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fopenvpn-pihole/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonwep","download_url":"https://codeload.github.com/simonwep/openvpn-pihole/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622983,"owners_count":20968575,"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":["containerization","docker","docker-compose","docker-image","openvpn","openvpn-installer","openvpn-server","pihole"],"created_at":"2024-09-26T13:02:19.961Z","updated_at":"2025-04-07T09:18:41.291Z","avatar_url":"https://github.com/simonwep.png","language":"Shell","funding_links":["https://github.com/sponsors/simonwep","https://patreon.com/simonwep","paypal.me/simonreinisch","buymeacoffee.com/aVc3krbXQ","https://www.buymeacoffee.com/aVc3krbXQ","https://www.patreon.com/simonwep"],"categories":[],"sub_categories":[],"readme":"\u003ch3 align=\"center\"\u003e\n    \u003cimg src=\"https://user-images.githubusercontent.com/30767528/91841822-4a3a5900-ec53-11ea-92fe-4bde2acccac4.png\" alt=\"Logo\" width=\"500\"\u003e\n\u003c/h3\u003e\n\n\u003ch3 align=\"center\"\u003e\n    \u003ca href=\"https://openvpn.net\"\u003eOpenVPN\u003c/a\u003e and \u003ca href=\"https://pi-hole.net\"\u003ePiHole\u003c/a\u003e wrapped up in a docker-compose setup\n\u003c/h3\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/simonwep/openvpn-pihole/actions?query=workflow%3Amain\"\u003e\u003cimg\n     alt=\"CI Status\"\n     src=\"https://github.com/simonwep/openvpn-pihole/actions/workflows/main.yml/badge.svg\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/simonwep\"\u003e\u003cimg\n     alt=\"GitHub Sponsors\"\n     src=\"https://img.shields.io/badge/GitHub-sponsor-0A5DFF.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/aVc3krbXQ\"\u003e\u003cimg\n     alt=\"Buy me a Coffee\"\n     src=\"https://img.shields.io/badge/Buy%20Me%20A%20Coffee-donate-FF813F.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.patreon.com/simonwep\"\u003e\u003cimg\n     alt=\"Support on Patreon\"\n     src=\"https://img.shields.io/badge/Patreon-support-FA8676.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\nThis project is a composition out of the official [PiHole docker image](https://github.com/pi-hole/docker-pi-hole) and a hand-crafted [openvpn-image](openvpn-docker) to set up a ready-to-use VPN with PiHole as dns-resolve in less than a minute.\nIts configuration is kept simple, you can add / remove clients and easily extend it as the configuration is stored in a centralized and easily manageable way.\nEnjoy!\n\nThe main configuration for this is inspired by [mr-bolle/docker-openvpn-pihole](https://github.com/mr-bolle/docker-openvpn-pihole), [pknw1/openvpn-pihole-docker](https://github.com/pknw1/openvpn-pihole-docker)\nand [kylemanna/docker-openvpn](https://github.com/kylemanna/docker-openvpn).\n\n## Table of Contents\n- [Setup](#setup)\n  - [Generating `.ovpn` files](#generating-ovpn-files) (or a [list](#generating-a-list-of-certificates))\n  - [Revoking `.ovpn` files](#revoking-ovpn-files)\n  - [Renewing certificates](#renewing-certificates)\n- [Configuration](#configuration)\n  - [OpenVPN](#openvpn)\n  - [PiHole](#pihole)\n- [FAQ \u0026 Recipes](#faq--recipes)\n  - [Launching multiple openvpn instances with different protocol/port config](#launching-multiple-openvpn-instances-with-different-protocolport-config)\n- [Troubleshooting](#troubleshooting)\n  - [Port 53 is already in use](#port-53-is-already-in-use)\n- [Contributing](#contributing)\n\n## Setup\n\nFirst clone this repository:\n\n```sh\ngit clone https://github.com/simonwep/openvpn-pihole.git\ncd openvpn-pihole\n```\n\n\u003e [!CAUTION]\n\u003e If you share your VPN with others, it's highly recommended changing the admin password for the PiHole dashboard in the [docker-compose.yml](docker-compose.yml) file now.\n\nAfter you've installed all the pre-requisites, you can run (make sure you're using the latest [docker](https://docs.docker.com/get-docker/) version):\n```sh\nsudo docker compose up -d\n```\n\nAfter this is done you'll find two new folders inside of this repository - the `/openvpn` folder will contain all of your certificates as well as an easy-rsa configuration file.\n`/pihole` will contain the content of `/etc/pihole` and `/etc/dnsmasq.d`.\n\nIf you want to migrate settings or your query-database, you can now copy it into the corresponding folder in `/pihole` :)\nYou'll also be able to import your config as usual in the docker dashboard.\n\nThe pihole admin dashboard can only be reached through the vpn under [http://pi.hole](http://pi.hole).\n\n\u003e [!NOTE]\n\u003e If you're using a VPS make sure to open `1194/udp`!\n\n### Generating `.ovpn` files\n\n\u003e [!NOTE]\n\u003e Before you generate any client certificate, you must update the host in [client configuration](openvpn/config/client.conf).\n\u003e This file will be used as base-configuration for each `.ovpn` file! You probably at least want to change the IP address to your public one.\n\n```sh\n./clients.sh add \u003cpassword\u003e \u003cnames...\u003e\n```\n\n### Revoking `.ovpn` files\n\n```sh\n./clients.sh remove \u003cname\u003e\n```\n\n\u003e [!WARNING]\n\u003e Revoked certificates won't kill active connections, you'll have to restart the service if you want the user to immediately disconnect:\n\n```sh\nsudo docker compose restart openvpn\n```\n\n### Renewing certificates\n\nDepending on the configuration of [easy-rsa](openvpn/config/easy-rsa.vars) the certificates will expire at some point.\nBy default, that is after two years, to renew it you can simply remove the `pki` folder that contains the certificate authority.\nAfter restarting the service, a new CA will be generated.\n\n```sh\ndocker compose down\nrm -rf ./openvpn/pki\ndocker compose up -d\n```\n\nKeep in mind, that after that you have to re-generate all `.ovpn`-files.\n\n## Configuration\n\n### OpenVPN\n\nConfiguration files (such as [`server.conf`](openvpn/config/server.conf) and [`client.conf`](openvpn/config/client.conf)) are stored in [openvpn/config](openvpn/config).\nThey get copied every time the instance gets spawned so feel free to change / update them any time.\n\n### PiHole\n\nWe're always using the very latest PiHole version.\nStart the PiHole service at least once to edit configuration files manually.\n\n## FAQ \u0026 Recipes\n\n### Launching multiple openvpn instances with different protocol/port config\nFirst copy the [openvpn](openvpn) directory including [openvpn/config](openvpn/config) (copy just the `config` folder!), then add another service to [docker-compose.yml](docker-compose.yml).\n\nExample assuming we want to name our second openvpn instance `openvpn-tcp-443`:\n```sh\nmkdir openvpn-tcp-443\ncp -r openvpn/config openvpn-tcp-443\n```\n\nYou can now make changes to our new config files in `openvpn-tcp-443/config`. Change `proto` to `tcp` and `port` to `443`,\nyou'll also need to comment out `explicit-exit-notify 1` as this is only compatible with `proto udp` (update both `server.conf` and `client.conf`!).\n\nNow add our new service:\n```yaml\n# ... other services\n    openvpn-tcp-443:\n        container_name: openvpn-tcp-443\n        build: ./openvpn-docker\n        ports:\n            - 443:443/tcp\n        volumes:\n            - ./openvpn/pki:/etc/openvpn/pki # Keep the PKI\n            - ./openvpn-tcp-443/clients:/etc/openvpn/clients\n            - ./openvpn-tcp-443/config:/etc/openvpn/config # !! We're using our second configuration\n        cap_add:\n            - NET_ADMIN\n        restart: unless-stopped\n# ... other services\n```\n\n\u003e Keep in mind that if you want to generate a client-config for that service  we've just made you'll\n\u003e have to use the openvpn-tcp-443 container e.g. `sudo docker exec openvpn-tcp-443 bash /opt/app/bin/genclient.sh \u003cname\u003e`.\n\n## Troubleshooting\n\n### Port 53 is already in use\n\n\u003e ERROR: for pihole  Cannot start service pihole: driver failed programming external connectivity on endpoint pihole (...): Error starting userland proxy: listen tcp 0.0.0.0:53: bind: address already in use\n\nYou'll need to disable the local dns-server, see [this](https://askubuntu.com/questions/907246/how-to-disable-systemd-resolved-in-ubuntu) and [this](https://askubuntu.com/questions/191226/dnsmasq-failed-to-create-listening-socket-for-port-53-address-already-in-use) askubuntu thread.\nYou can stop, disable and mask the `systemd-resolved` service using the following commands:\n\n```sh\nsudo systemctl stop systemd-resolved\nsudo systemctl disable systemd-resolved\nsudo systemctl mask systemd-resolved\n```\n\n## Contributing\n\nCheckout the [contribution guidelines](.github/CONTRIBUTING.md) :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonwep%2Fopenvpn-pihole","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonwep%2Fopenvpn-pihole","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonwep%2Fopenvpn-pihole/lists"}