loading . . . _This guide has been completely rewritten using**wg-easy** as the foundation since itâs an actively maintained project and is much easier to use. The old version was based on wireguard-ui, which no longer seems to receive support._
WireGuard is one of the best VPN choices for self-hosting enthusiasts who want reliable and secure communication. It encrypts your internet traffic and routes it through a private network, making it impossible for anyone to intercept your data.
What makes it such a popular and preferred choice? Itâs simple â compared to most options, WireGuard offers reliability, simplicity, speed, and security, hard to beat. However, setting it up from scratch can be a complicated process. For example, hereâs how to do it on Ubuntu.
And here is the moment where wg-easy steps in. Itâs a free and open-source tool designed to simplify the deployment and management of a WireGuard VPN server, providing a user-friendly web-based interface that streamlines the configuration and management of WireGuard connections.
In this guide, Iâll show you how to set up WireGuard using wg-easy with Docker Compose, making it as simple as possible for you to configure and manage your VPN server and clients.
By the end, youâll have a fully functional VPN solution with an easy-to-use web-based management interface. Trust me, if you follow the steps below, youâll have everything set up in just 20â30 minutes. Yes, itâs that easy with wg-easy.
But before we proceed to action, let me briefly introduce a bit of theory to help you better understand wg-easy and WireGuard and how they relate to each other.
Table of Contents
[Open][Close]
* WireGuard + wg-easy: A Match in Heaven
* Step 1: Ensure You Have Docker and Docker Compose Installed
* Step 2: Set Up WireGuard VPN Server & wg-easy with Docker Compose
* Step 3: Run the Container with Docker Compose
* Step 4: Log in to the WireGuard VPN Server
* Step 5: Create a New WireGuard Client Configuration
* Step 6: Setting Up WireGuard Client
* Connecting to WireGuard from a Linux PC using Network Manager
* Connecting to WireGuard from a Mobile Device
* Conclusion
## WireGuard + wg-easy: A Match in Heaven
First and foremost, itâs crucial to understand that wg-easy _contains_ and _runs_ WireGuard, but it does so indirectly, with the help of the host system.
The core WireGuard functionality â meaning the actual VPN engine â is still handled by the Linux host because WireGuard itself is a module built directly into the Linux kernel (_wireguard.ko_) or a cross-platform user-space implementation (_wireguard-go_) for systems where the native WireGuard kernel module is unavailable.
In simple terms, _wg-easy_ âorchestratesâ WireGuard, handling all the complicated tasks, such as setting up firewall rules, managing the VPN interface, maintaining WireGuard server/client configuration files, etc., with just a few simple clicks.
However, if your Linux distribution doesnât have WireGuardâs module available in the kernel, wg-easy alone wonât work properly because it doesnât include a WireGuard kernel module inside the container. It just _uses_ this module, which _must_ already be available on the host operating system.
The good news is that kernel 5.6 (released in March 2020) and later versions include it by default. This means that, almost certainly, the distribution you are going to install WireGuard and wg-easy on already has everything you need to move on. Of course, you can always check your kernel version by running `uname -r` in the terminal.
Okay, I think thatâs enough as an explanation. Now, letâs move on to the actual installation.
## Step 1: Ensure You Have Docker and Docker Compose Installed
Docker is a platform for creating and running applications in lightweight containers, which makes deploying and managing software much more effortless.
At the same time, Docker Compose, which can be thought of as an add-on to Docker, is a tool used for defining and running multi-container Docker deployments âpackagedâ as a single application or running a single container more conveniently and descriptively, using â _docker-compose.yml_ â files so that we will use it in that case.
The first step is to ensure that Docker is installed on your machine. The easiest way to do this is by running:
docker --versionCode language: Bash (bash)
Verify if Docker is installed.
If you receive a message like the one above, all is well. You have Docker installed on your system.
However, if you get something like â _bash: docker: command not foundâŠ_ â in response, thereâs no room for worry. Weâve got you covered. Our detailed guides on installing Docker on Ubuntu, Debian, Arch, Linux Mint, Fedora, AlmaLinux, Rocky Linux, and Raspberry Pi will help you get it up and running on your system quickly and easily.
The next step is to ensure that Docker Compose is also installed on your system. Similar to the above example, run:
docker-compose --versionCode language: Bash (bash)
Verify if Docker Compose is installed.
If the command output is similar, congratulations! You have everything you need to install the WireGuard VPN server with the wg-easy web interface by using Docker Compose.
However, if the message is something like â _bash: docker-compose: command not foundâŠ_ â just run the two commands below, and you will have Docker Compose installed on your system in seconds.
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-composeCode language: Bash (bash)
In that case, remember, when running the tool, to type `docker-compose` instead of `docker compose`.
Additionally, to be clear, Compose only works if Docker is already installed and running. For an in-depth introduction, check out our comprehensive guide.
## Step 2: Set Up WireGuard VPN Server & wg-easy with Docker Compose
As we already said, Docker Compose allows you to deploy containers by using a â _docker-compose.yml_.â So, first, create a â _wireguard_ â directory and switch to it.
mkdir wireguard
cd wireguardCode language: Bash (bash)
Then, using your preferred text editor, create a file named â _docker-compose.yml_ â (inside the â _wireguard_ â directory):
vim docker-compose.ymlCode language: Bash (bash)
Add the following content, then save and exit the file.
services:
wg-easy:
environment:
- LANG=en
- WG_HOST=<YOUR-HOST'S-PUBLIC-IP>
- PASSWORD_HASH=<WEB-UI-PASSWORD>
- UI_CHART_TYPE=0
image: ghcr.io/wg-easy/wg-easy
container_name: wg-easy
volumes:
- ./data:/etc/wireguard
ports:
- 51820:51820/udp
- 51821:51821/tcp
restart: unless-stopped
cap_add:
- NET_ADMIN
- SYS_MODULE
sysctls:
- net.ipv4.ip_forward=1
- net.ipv4.conf.all.src_valid_mark=1Code language: YAML (yaml)
Before we move on with the deployment, there are a couple of quick changes we need to make to the file above. First, replace â _< YOUR-HOSTâS-PUBLIC-IP>_â with your serverâs real public IP address â the one thatâs reachable from the Internet. If youâre not sure what it is, you can easily find it by running `curl ifconfig.me` in your terminal or looking here.
Of course, instead of using an IP address, you can also use a valid FQDN if you have a domain name under your control â for example, something like â _vpn.example.com_.â
Also, port 51820, which WireGuard uses, must be open and accessible from the Internet. If youâre running any firewalls, make sure this port isnât being blocked. As for port 51821, thatâs the one the wg-easy web interface lives on. I _highly_ recommend locking it downâideally, only trusted IP addresses should be allowed to access it.
Now, letâs create a password to access the wg-easy web UI. Just run the command below, but be sure to replace â _mypassword_ â with the actual password you want to use. Itâll generate the needed bcrypt hash for you automatically.
docker run ghcr.io/wg-easy/wg-easy wgpw mypasswordCode language: Bash (bash)
Password generation for access to the wg-easy web UI.
Thereâs a little quirk you should be aware of. Open a text editor and copy the content inside the single quotes from the line that says â _PASSWORD_HASH_.â Normally, youâll notice that at the very beginning of the string, the â _$_ â symbol appears three times. What you need to do is add an extra â _$_ â right after each one.
In other words, if we follow the example above, it should go from this:
$2a$12$iTEW66I7tLr3bVOCyPkdXeR5l0WEmvB2ee8Rk.qL7CpN2lpDGnw9WCode language: Makefile (makefile)
To this:
$$2a$$12$$iTEW66I7tLr3bVOCyPkdXeR5l0WEmvB2ee8Rk.qL7CpN2lpDGnw9WCode language: Makefile (makefile)
Now, take this string and use it to replace â _< WEB-UI-PASSWORD>_â in the â _docker-compose.yml_ â file above.
Finally, it is essential to note that the Docker volume preserving the WireGuard configuration settings (â _data_ â) will be created and made available in the current â _wireguard_ â directory. Modify the file above if you want it somewhere else. For example, â _/srv/my-wireguard-conf:/etc/wireguard_.â
## Step 3: Run the Container with Docker Compose
Okay, we are ready to run our WireGuard VPN server using Docker Compose. To do this, execute the following command from the current â _wireguard_ â directory where the â _docker-compose.yml_ â file is located.
docker compose up -dCode language: Bash (bash)
Since the required Docker image was already downloaded when you ran the password generation for the wg-easy web UI earlier, the container should start up in just a few seconds.
Running WireGuard VPN Server with Docker Compose.
## Step 4: Log in to the WireGuard VPN Server
You can now open your browser and navigate to â _http://server-ip-address:51821_.â The wg-easy login page will greet you. Enter the password you set up above, then hit the â _Sign In_ â button.
wg-easy UI login page.
And here is the moment to provide an essential, if not critical, clarification. This guide uses an unencrypted HTTP connection to access the wg-easy UI. I only do this because itâs a temporary virtual machine in our testing lab that I created for this tutorial.
However, in a real production scenario, _always_ use only a secure HTTPS connection to access the wg-easy UI management interface. You can ensure this by placing a reverse proxy in front of it, such as Nginx Proxy Manager, Caddy, Traefik, etc.
## Step 5: Create a New WireGuard Client Configuration
Click the â _+ New Client_ â button to set up the configuration for your first VPN client, which will connect to the WireGuard server to establish a VPN connection. In a moment, Iâll show you how to import it onto your workstation or mobile phone.
Create a WireGuard client configuration.
In the opened modal window, type a name for the WireGuard client and click the â _Create_ â button.
Create a WireGuard client configuration.
This is where the real magic of wg-easy shines. It automatically takes care of everything you need to set up the WireGuard client behind the scenes. And trust me, thatâs no small task â generating public and private keys, setting up the IP range and address, configuring the DNS server, specifying the endpoint server, and more.
Sure, you could do all of this manually by editing the configuration file yourself. But it would be time-consuming, especially if youâre not familiar with every little detail, and thereâs always the risk of making a mistake. Thankfully, the developers behind wg-easy have made it so you donât have to worry about any of that.
You only need to click the download button to grab your WireGuard client configuration file. Itâll save a file locally on your computer, just like in the â _my-desktop-pc.conf_ â example.
Download the client configuration for WireGuard.
Now, letâs take a look at how to import this file into the device we want to securely connect to the WireGuard server and keep its online presence safe and private.
## Step 6: Setting Up WireGuard Client
This is, without a doubt, the most exciting part for a simple reasonâitâs when weâll see the results of our efforts so far, setting up the client and connecting it to the WireGuard VPN server.
From here on, the approach is specific as to whether we will initiate an encrypted VPN connection from a mobile device, such as a phone or tablet, or a desktop workstation, laptop, etc. Iâll cover both cases.
### Connecting to WireGuard from a Linux PC using Network Manager
Importing the file is super easy with NetworkManagerâs command-line tool, `nmcli`. Just run the command below, making sure to use the path to your WireGuard client configuration file as the final argument.
nmcli connection import type wireguard file my-desktop-pc.confCode language: Bash (bash)
Importing Network Manager WireGuard profile.
Go and look at the available network connections on your Linux system â you will see that our new WireGuard VPN connection is added and ready to use. Connect and enjoy a private online presence.
Network Manager connections.
To ensure everything works properly, send a ping from your desktop (WireGuard client) machine to the WireGuard serverâs private network address (10.8.0.1 by default).
ping -c 3 10.8.0.1Code language: Bash (bash)
Test connectivity to the WireGuard VPN server.
Something here is the moment when you have every reason to congratulate yourself because your WireGuard VPN tunnel is working as expected.
If you head back to the wg-easy interface, youâll see a small dark red dot blinking next to the avatar for the profile you just connected. Thatâs your sign that the client is online. You can also double-check by looking at the data transfer stats â they wonât be stuck at zero anymore.
WireGuard connected peers.
Flip the toggle switch off to stop the client from communicating with the WireGuard VPN server.
### Connecting to WireGuard from a Mobile Device
Things are considerably easier when you need to connect your mobile device to the WireGuard VPN server. You only need to download the official WireGuard client for your operating system. iOS users should visit the Apple App Store, while Android users should go to the Google Play Store.
After installing the app on your mobile device, from the wg-easy UI, click the corresponding userâs â _Show QR Code_ â button, which displays the QR code containing all the information required to import WireGuardâs VPN profile.
Preview WireGuardâs QR profile code.
Next, open the WireGuard app on your mobile device, select â _Add a tunnel_ ,â then â _Create from QR code._ â Scan the code displayed on the monitor screen, and thatâs it. The profile will be imported automatically.
Import WireGuardâs VPN profile on a mobile device.
Then, switch on the profile, and your device will connect to the WireGuard VPN server.
## Conclusion
With its modern cryptography, simplicity, and high-performance capabilities, WireGuard has quickly become a go-to choice for VPN solutions, appealing to numerous Internet privacy advocates and businesses that want to protect their personal and confidential information from prying eyes, hackers, and cybercriminals.
Of course, you can set up the wg-easy container with various additional options. So, if youâd like to customize your WireGuard server even further, you can check out all the details here.
Thank you for using this guide and for your time! I hope I have been helpful. Any opinions and comments are most welcome in the section below. https://linuxiac.com/how-to-set-up-wireguard-vpn-with-docker/