{"id":13419498,"url":"https://github.com/ezaquarii/vpn-at-home","last_synced_at":"2025-09-29T17:32:05.328Z","repository":{"id":77111428,"uuid":"116600317","full_name":"ezaquarii/vpn-at-home","owner":"ezaquarii","description":"1-click, self-hosted deployment of OpenVPN with DNS ad blocking sinkhole","archived":true,"fork":false,"pushed_at":"2020-08-09T15:10:31.000Z","size":83717,"stargazers_count":1108,"open_issues_count":8,"forks_count":90,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-09-22T20:02:45.895Z","etag":null,"topics":["adblock","ansible","easy-rsa","linux","openbsd","openvpn","privacy","privacy-protection","vpn"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ezaquarii.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","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}},"created_at":"2018-01-07T21:25:06.000Z","updated_at":"2024-09-16T19:52:41.000Z","dependencies_parsed_at":"2023-02-28T16:16:49.872Z","dependency_job_id":null,"html_url":"https://github.com/ezaquarii/vpn-at-home","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezaquarii%2Fvpn-at-home","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezaquarii%2Fvpn-at-home/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezaquarii%2Fvpn-at-home/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezaquarii%2Fvpn-at-home/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ezaquarii","download_url":"https://codeload.github.com/ezaquarii/vpn-at-home/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219874662,"owners_count":16554606,"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":["adblock","ansible","easy-rsa","linux","openbsd","openvpn","privacy","privacy-protection","vpn"],"created_at":"2024-07-30T22:01:16.855Z","updated_at":"2025-09-29T17:32:02.847Z","avatar_url":"https://github.com/ezaquarii.png","language":"Python","funding_links":["https://www.patreon.com/ezaquarii"],"categories":["Python","\u003ca id=\"d62a971d37c69db9f3b9187318c3921a\"\u003e\u003c/a\u003e工具","HarmonyOS"],"sub_categories":["\u003ca id=\"8ea8f890cf767c3801b5e7951fca3570\"\u003e\u003c/a\u003e公网访问局域网","Windows Manager"],"readme":"This software is no longer supported\n====================================\n\nI'm no longer maintaining this software.\n\nVPN​@​Home - 2.1.1\n==================\n\n.. raw:: html\n\n    \u003ccenter\u003e\n        \u003ca href=\"https://t.me/vpnathome\"\u003e\u003cimg src=\"https://img.shields.io/badge/Telegram%20Chat-Online-success.svg\"\u003e\u003c/a\u003e\n        \u003ca href=\"./LICENCE.txt\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-GPL3-blue.svg\"\u003e\u003c/a\u003e\n        \u003ca href=\"https://www.vultr.com/?ref=7515725\"\u003e\u003cimg src=\"https://img.shields.io/badge/use-vultr-brightgreen.svg\"\u003e\u003c/a\u003e\n        \u003ca href=\"https://www.patreon.com/ezaquarii\"\u003e\u003cimg src=\"https://img.shields.io/badge/donate-patreon-brightgreen.svg\"\u003e\u003c/a\u003e\n    \u003c/center\u003e\n    \u003ccenter\u003e\n        \u003ca href=\"https://vimeo.com/308879491\"\u003e\u003cimg src=\"vimeo.png\" width=\"512\"\u003e\u003c/a\u003e\n    \u003c/center\u003e\n\nTL;DR\n=====\n\nWhat?\n-----\n\n1-click deployment of OpenVPN with DNS ad blocking sinkhole. Deploys to your favorite VPS machine.\nCreated with **Vue.js**, **Semantic UI** and **Django**. And with love, of course.\n\nWhere I can find packages\n-------------------------\n\nUbuntu 20.04 users can use pre-built packages:\n\n::\n\n    $ sudo add-apt-repository ppa:ezaquarii/packages\n    $ sudo apt-get update\n    $ sudo apt-get install vpnathome\n    $ firefox http://localhost:8000\n\nOther distro dwellers must follow manual instructions found below.\nDebian package building is automated, so there should be no trouble.\n\nI do not maintain older Ubuntu versions as I don't run them.\nThere is a package for 18.04 that Launchpad built for me automatically,\nbut it is known to be broken.\n\nWhat if I need halp!\n--------------------\n\nYou can ask on `Telegram group chat \u003chttps://t.me/vpnathome\u003e`_ or mail me (e-mail in git history).\n\nShow me the screenshots\n-----------------------\n\n.. image:: home.png\n   :width: 512\n   :align: center\n\n.. image:: deployment.png\n   :width: 512\n   :align: center\n\n.. image:: settings.png\n   :width: 512\n   :align: center\n\n\nFeedback and pull requests are welcome.\n\nLegal mumbo-jumbo\n=================\n\nOpenVPN is a registered trademark of OpenVPN  Inc.\n© 2002-2019 OpenVPN Inc.\n\nThis project is not endorsed by, sponsored or affiliated with OpenVPN Inc.\n\nBrief\n=====\n\nManaging OpenVPN with PKI authentication is hard. Managing anything beyond hello-world using ``easy-rsa`` package\nis a major issue - I could never maintain a config for more than a day. Other solutions are too *\"enterprise\"*\nfor a personal installation or were designed for a tin-foil hat, crypto maniacs hiding from NSA/GCHQ.\n\nThis app provides easy management console to keep OpenVPN configuration files in one place, provided in self-contained,\neasily deployable, clickable package. It's not designed for security - it's meant just to be **good enough**.\n\nAnd that works for me better than \"no VPN at all\".\n\nFeatures:\n\n#. 1-click deployment of OpenVPN server to your favorite VPS provider\n#. DNS cache and ad blocking for VPN connected clients\n#. OpenVPN clients management\n#. Generation of self-contained ovpn profiles for servers and clients\n#. Profiles can be sent by e-mail to owner or downloaded as files\n#. Tested on Ubuntu 18.04 and OpenBSD 6.4 (Vultr VPS)\n\nThat's all folks.\n\n.. note:: This is a work-in-progress app, hacked together during x-mas break to solve a specific need of mine.\n          Feel free to submit PRs with improvements.\n\nFAQ\n===\n\n**Why?**\n\nTo quickly deploy VPN server when I need it. I can spin VPS and deploy my own VPN any time, tear it down\nwhen not used and not paying a monthly fee for all my devices.\n\nI travel a lot and I need to have on-demand VPN when browsing stuff in hotels, airports, etc.\n\n**Does it hide my ass? Can I haz torrentz?**\n\nNo. Do not use it to do any stupid things.\n\n**Is the app secure?**\n\nSince the app manages OpenVPN server deployment, it must have root access to the VPN\nmachine. There is no separate deployment agent (yet), as it would over-complicate things.\nIt is not wise to keep it facing the open internet, I guess, so please don't do it.\n\n**So how to host it?**\n\nPreferably on your internal network. Keep the server bound to *localhost* and connect to it\nvia SSH tunnel. This way you don't need to configure SSL certificate and a lot of security\nheadaches go away.\n\nI use it installed on my private laptop, the same way I use CUPS (printer stuff, aka localhost-colon-six-three-one).\n\n**Why it contains those tar.gz files in pypi directory?**\n\n1. To enable offline builds;\n2. To ship entire app in form of a source code, which is required by Launchpad;\n3. To have reproducible builds, independent from external repositories;\n\nPlease read about\n`npm package that broke the internet \u003chttps://duckduckgo.com/?q=npm+package+that+broke+the+internet\u003e`_ to undestand\nthe downside of pulling your dependencies from 3rd party sources during build time.\n\n**How to change server address after it is created?**\n\nUse Django Admin panel to modify host field and re-deploy. All client configs must be re-deployed too.\nYou can try playing with DynDNS to work around it.\n\n**Why Ansible? It's slow and weights 30MB.**\n\n#. It does the job like a champ lifting tons of system complexity\n#. Zero-effort deployment (no master nodes, etc)\n#. Very easy to extend\n#. I'd like to have more complex setup in the future and bash won't cut it\n\n**Why not language X**?\n\nI believe Python is optimal solution considering platform maturity, libraries quality and\nskills proliferation. There is not much choice for the frontend.\n\nProject structure\n=================\n\nThe project is split into *backend*, *frontend*. and *ansible* scripts.\n\nThe backend is written in **Django** and **Django REST Framework**. The frontend is a **Vue.js** SPA application served by **Django**.\nThat division makes the build slightly more complicated, but provided *Makefiles* make it a breeze. It should just work.\n\n**Ansible** is a set of scripts to deploy OpenVPN automatically either on localhost or remote machine.\n\nScripts located in **bin** are created either to automate and facilitate various tasks or provide a glue.\nAll scripts have internal documentation (or should have).\n\nInstallation\n============\n\nPrerequisites\n-------------\n\n#. Working Node.js installation (tested with 9.3.0)\n#. Python 3 with virtualenv\n#. GNU Make (or compatible)\n#. Ansible (tested with 2.5.0, but no fancy functionality is used)\n#. OpenVPN in ${PATH}\n#. OpenSSL in ${PATH}\n#. OpenSSH in ${PATH}\n#. Internet connection (no off-line build possible)\n\nDeployment\n----------\n\nFor development\n~~~~~~~~~~~~~~~\n\nAfter cloning the repository, you can easily deploy the app for development:\n\n::\n\n    $ git clone https://github.com/ezaquarii/vpn-at-home\n    $ cd vpn-at-home\n    $ make install_dependencies  # apt-get only, other distros must do it manually\n    ...follow instructions to install packages and Node.js...\n    $ exec bash  # reload your shell to update $PATH and reload bashrc, so Node.js works, exec will replace the process\n    $ make devel\n    ... backend is bootstrapped ...\n    ... frontend is bootstrapped ...\n    $ make runserver\n\nOpen ``http://localhost:8001/`` and you should be able to log-in. Your app data\n(config, ssh keys, etc) is stored in ``data`` directory in project's root.\n\nIf you completely mess up, delete data and run ``env/bin/init.sh`` to boostrap\nthe app again.\n\nFor production - Debian package\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPackage deployment is supported on *Ubuntu*. *Debian* should be supported, but I didn't test it there.\n\n::\n\n    $ make deb\n    $ make install_deb\n\nOpen ``http://localhost:8000`` and follow on-boarding tutorial.\n\n.. note:: Building ``deb`` package calls ``make distclean``, which will zap your development\n          configuration. Build outside devel environment if you want to preserve your config.\n\nThe package needs virtually zero configuration:\n\n- ``deb`` is self-deployable, as it contains entire virtualenv\n- installs into ``/usr/lib/vpnathome`` (referred to as ``${ROOT}``)\n- ``systemd`` service script ``vpnathome.service`` is installed and starts by default\n- ``daphne`` runs on ``http://127.0.0.1:8000`` - bound to **localhost** only\n- Application ``$HOME`` is ``/var/lib/vpnathome`` and all application data is stored there\n- Bootstrapping script to automate app configuration in located in ``/var/lib/vpnathome/init.sh``\n\nOpenVPN server deployment\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nOnce the app is up and running, you can log in as admin (using credentials set during bootstrapping phase) and\ncreate your server.\n\nAfter a server is configured, you can deploy it using provided **Ansible** scripts by clicking ``Deploy``\noption in server list. Beware that *Ansible* will modify the target system!\n\n#. required packages will be installed\n#. firewall rules will be altered\n#. IPv4 forwarding will be enabled\n\nIf the app fails to log into a target system, make sure you have the correct SSH keys uploaded to the server\n(check out ``data/ssh`` directory).\n\nConfiguration\n-------------\n\nIf ``make devel`` was run, the app is up and running in development mode with default development\nconfiguration:\n\n- Admin login is *admin@locahost*\n- Admin password is *admin1234*\n- Database is located in ``${PROJECT_ROOT}/data/db/db.sqlite3``\n- Settings have ``development`` flag set to true ``true`` causing frontend code to be taken from ``frontend`` project\n\nActivate Python virtualenv when before running ``manage.py``!\nTo set new superuser, use ``${PROJECT_ROOT}/env/bin/manage.py set_admin \u003cemail\u003e \u003cpass\u003e`` command.\n\nApp config\n~~~~~~~~~~\n\nConfiguration is loaded from ``settings.json`` located in ``data`` directory in the current working directory.\n\nThe settings file is generated during bootstrap stage (``init.sh``), so there is no need to generate it\nmanually. However, should you need to generate the script during development, you can do it with a supplied\nDjango management command:\n\n::\n\n    $ source ${PROJECT_ROOT}/env/bin/activate  # activate Python virtual environment first!\n    $ ${PROJECT_ROOT}/env/bin/manage.py configure --help\n\nOnce the file is generated, you must review and accept it by flipping the ``configured`` flag.\n\nAlternative way is to run ``init.sh``:\n\n::\n\n    $ ${PROJECT_ROOT}/env/bin/init.sh [--no-smtp]\n\nJust follow the wizard. It will accept the configuration for you, so there is no need to flip the flag.\n\n.. note:: ``settings.json`` is excluded from Git repository, so you can safely put your real e-mail credentials there\n          during development.\n\nOpenVPN config\n~~~~~~~~~~~~~~\n\nOpenVPN configuration is generated from templates in ``vpnathome.apps.openvpn.templates``. If the default\nconfiguration doesn't suit your needs, you can alter templates directly there.\n\nThere is no frontend config editor, although I was thinking about it.\n\nClient connection\n-----------------\n\nObtaining client config\n~~~~~~~~~~~~~~~~~~~~~~~\n\nVPN config files can be send to e-mail account of a user that created a config or downloaded.\nOnce downloaded, the config file (OVPN) can be used directly with OpenVPN client.\n\nDNS check\n~~~~~~~~~\n\nIf server was deployed with DNS cache enabled, DNS is forwarded to connecting client.\nDepending on your network this might be slower or faster than popular DNS servers or DNS of your ISP.\n\nTo verify if your queries are forwarded to VPN DNS:\n\n::\n\n    ping gateway.vpnathome\n    PING gateway.vpnathome (172.30.0.1) 56(84) bytes of data.\n    64 bytes from _gateway (172.30.0.1): icmp_seq=1 ttl=255 time=46.5 ms\n    64 bytes from _gateway (172.30.0.1): icmp_seq=2 ttl=255 time=48.7 ms\n\nwhere ``172.30.0.1`` will be your choosen VPN gateway IP. Check ``systemd-resolve --status`` if DNS servers are\nproperly pushed.\n\nDevelopment\n===========\n\nWant to jump in? Fantastic.\n\nI made it as easy to start development as possible. Top-level project directory contains 2 subprojects:\n``backend`` and ``frontend``.\n\nTop-level ``Makefile`` delegates targets to sub-projects and is provided for convenience. Once ``make devel`` is\ndone, you can work inside individual subproject with your favourite IDE.\n\nI personally use *JetBrains WebStorm* and *PyCharm*, but you can use whatever you want.\nIDE files are not even in the repo.\n\nBackend subproject\n------------------\n\nThis is the **Django** app. Mostly REST API + single frontend serving view.\nApp modules have brief documentation inside ``__init__.py``. Docs are kept up-to-date, as I strongly\nbelieve in code documentation.\n\nProvided ``Makefile``'s default target displays help:\n\n::\n\n    $ make\n    Welcome to VPN@Home make system\n    \n    Available top-level targets:\n     * install_dependencies - convenient shortcut to install build dependencies (packages and node.js)\n     * devel                - bootstrap both projects for development\n       * devel_backend      - bootstrap backend for development (dependency of devel)\n       * devel_frontend     - bootstrap frontend for development (dependency of devel)\n     * distclean            - clean projects, delete all data (start from 'git clone' state)\n     * runserver            - run development server (manage.py runserver)\n     * deb                  - build debian package\n       * remove_deb         - remove installed Debian package\n       * purge_deb          - purge installed Debian package\n       * install_deb        - install previously built debian package\n\nIn development mode, frontend files are stored outside of this project, in ``frontend`` subproject. **Django** app\nwill pick static and templates from frontend build directory.\n\nWhen development mode is off, frontend resources are taken from ``vpnathome.apps.frontend`` app.\n\n**Django Debug Toolbar** is provided by default, should you need to check which templates are picked up.\n\nFrontend subproject\n-------------------\n\nFrontend sub-project contains **Vue.js** SPA served by **Django**. By default **Django** app will serve\nstable, production version of the frontend app directly.\n\nProvided ``Makefile``'s default target displays help:\n\n::\n\n    $ cd frontend\n    $ make\n    Welcome to VPN@Home make system - frontend sub-project\n    You need running node.js and npm.\n\n    Available targets:\n     * build-prod  - build production build; backend project is NOT updated\n     * build-devel - watch and make development build on change; output is written to './dist'\n     * install     - install packages from package.json\n     * distclean   - clean project, delete all data (start from 'git clone' state)\n\nTo start development of frontend code, you must first switch backend into development mode, by modifying ``data/settings.json``:\n\n::\n\n    {\n        ...\n        \"configured\": true,\n        \"development\": true,\n        \"debug_toolbar_enabled\": true,\n        ...\n\nDon't forget to restart the app. Once development mode is enabled, **Django** will load frontend from ``frontend/dist``\ninstead of ``vpnathome.apps.frontend``. You can verify this by inspecting site title - it should say\n*VPN@Home \u003cversion\u003e - development*. You can also use **Django Debug Toolbar** to troubleshoot the configuration.\n\n**Django** injects some initial state via ``\u003cscript\u003e...\u003c/script\u003e`` tag. See ``index.html`` and ``vpnathome.apps.frontent.views`` for\ndetails.\n\nLicence\n=======\n\nGNU GPL v3.\n\nKnown issues\n============\n\nI left this as the last point, hoping not to scare anybody.\n\n * frontend has 0% test coverage :o)\n * security is not a major concern for this app, I'm not running a CA company\n * no real user management - I rely on Django Admin panel for it\n * not tested on Windows, as I don't touch it even with a 10-foot stick, in rubber gloves - patches are welcome, however\n * no cert revocation (yet)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezaquarii%2Fvpn-at-home","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fezaquarii%2Fvpn-at-home","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezaquarii%2Fvpn-at-home/lists"}