DEV Community

Mike 'MJ' Johnson
Mike 'MJ' Johnson

Posted on

Oracle Free Tier + Wirehole + Ansible + Terraform = Amazing

This article was originally posted on


A couple weeks ago, Devin Stoke GitHub or Twitter posted a project called Wirehole, which I found really interesting. It combines Wireguard VPN, Pi-Hole ad-blocker and Unbound DNS server in Docker containers and runs them for free FOREVER on Oracle Cloud.

First, lets address that last line. It seems in an attempt to get in the game and draw in the nerd types to learn their cloud platform, Oracle has provided a very generous Free Forever tier which includes 2 1cpu/1gb ram instances for free forever. The catch is they are assigned to a specific zone in you chose "home" region, which caused some minor issues as we will see later. In any event, go get yourself an Oracle Cloud Infrastructure (OCI) account now.

The Project

This project deploys a number of Docker containers that you can use to create your own Wireguard based VPN service, network level ad blocking with Pi-hole and DNS over TLS connection in Unbound to help ramp up your network security. These pieces together were dubbed "Wirehole". Let's talk about each of these pieces.



WireGuard is a free and open-source software application and communication protocol that implements virtual private network (VPN) techniques to create secure point-to-point connections in routed or bridged configurations.

There are Wireguard clients for all major systems including mobile, so getting allowing your systems to communicate even when in geographically different locations becomes a cinch.



Pi-hole is a network-level advertisement and Internet tracker blocking application which acts as a DNS sinkhole and optionally a DHCP server, intended for use on a private network.

Think of it as a browser ad-blocker on steroids. It can protect any device that has the Pi-hole set as it's DHCP server including IoT and other 'Smart' devices in your home.



Unbound is a validating, recursive, caching DNS resolver. It is designed to be fast and lean and incorporates modern features based on open standards.

What this means is that it will help speed up your DNS by efficiently looking up all of your DNS traffic as well as caching entries for faster resolution. An added bonus is that in this implementation, we leverage Cloudflares super fast DNS and obfuscate our DNS queries from preying ISP eyes by leveraging DNS over TLS (DoT). Don't want your ISP to know how many times your browser requests DNS over TLS has you covered.

The Technology

This is a big one, as we leverage a number of technologies to achieve this deployment. I am not going to spend time going over every one, but I have listed them all below so you can go check it out yourself.


In order to run Terraform and Ansible that is included in this deployment, you will need to install Terraform and Ansible on your deployment system of choice. As you may be using any flavor of Linux, Windows or MacOS, I am only linking below to the general install instructions for each technology.

Also, you will need to go get some information from your Oracle Cloud account (which you set up earlier, right?)

Install Terraform:

Install Ansible:

Gather Info From OCI:

  • Oracle API signing key
  • User OCID
  • Tenancy OCID
  • Oracle Free Tier Availability Domain


Now that we have all the prep done, let's launch right into the install.

  1. Clone this repo to your deployment machine (where you installed Terraform and Ansible)

    git clone
    cd oci-wirehole
    terraform init
  2. Copy the terraform.tfvars.example file to terraform.tfvars

  3. Update ALL of the values above the Optional section at the bottom

  4. Run terraform plan and if this completes without any errors, proceed to the next step

  5. Run terraform apply --auto-approve and wait for the deployment to finish. When it is complete you should see a new inventory file in the ansible directory

  6. Change into the ansible directory by running cd ansible

  7. Copy the ansible.cfg.example to ansible.cfg. The default values provided will work, but feel free to update to your liking if you are familiar with Ansible

  8. Run ansible all -m ping and make sure it returns a pong confirming your connectivity. If there are no errors, move the the next step.

  9. Run anible-playbook main.yml and it will run through all of the provisioning steps and reboot the Wirehole host once to install updates.

  10. If everything went well, look in the ansible, files, wg_client_configs directory and you should find 10 configuration files for 10 Wireguard peers (Peer1 - Peer10)

  11. Install Wireguard on your desired devices:

  12. Copy the config from Peer1/peer1.conf to your client.
    i. (Recommended) If you only want DNS traffic to be passed to your Wirehole deployment, change the Allowed IPs to be Update your local DNS one the client to have and the first DNS server and another (such as as your secondary.

    Address =
    PrivateKey = ABCDEFGHIJK1234567890ABCDEFGHIJK1234567890
    ListenPort = 51820
    DNS =
    PublicKey = ABCDEFGHIJK1234567890ABCDEFGHIJK1234567890
    Endpoint = WIREHOLIP:51820
    AllowedIPs =

    ii. If you want all traffic to flow through through the VPN (there is a 10TB monthly limit on OCI free tier, so be aware) then you so not need to update the Allowed IPs, but you will still want to update your client DNS.

    Address =
    PrivateKey = ABCDEFGHIJK1234567890ABCDEFGHIJK1234567890
    ListenPort = 51820
    DNS =
    PublicKey = ABCDEFGHIJK1234567890ABCDEFGHIJK1234567890
    Endpoint = WIREHOLIP:51820
    AllowedIPs =, ::/0

    iii. If you are using mobile, you can scan the .png file that is included in the peer*/ folder to easily load that config. Once scanned, you can modify the allowed IPs the same way as shown above if you like.

  13. Start your Wireguard client and navigate to in your browser to reach the Pi-Hole admin panel. If you can reach it, everything should be working as expected.


Thanks to Devin Stokes for the initial project and to the creators of Pi-Hole, Wireguard and Unbound.

There are a few other tasks that you should do such as:

  • Secure port 22 on your OCI Wirehole instance to only allow access from your IP address or change the SSH port AND secure for extra security.
  • Backup your terraform.state file regularly or move the backend Terraform state storage to S3 for easy state management from multiple machines. Don't forget to enable versioning on the bucket.
  • Add more clients to the network using the additional Peer configuration files
  • Add more blocklists to your Pi-Hole for more effective ad blocking. Good collection of lists here:
  • Regularly running your Ansible playbook to make sure that your system and docker-containers are up to date.
  • Other regular management tasks

Top comments (0)