hosting notes, 2026-11-18.

This is the Terraform version of the Oracle setup. The 2020 steps assume a checkout containing Terraform files. The current WireHole project uses Docker Compose and has its own installation and upgrade instructions. Check Always Free eligibility for your chosen resources before applying a plan. The pricing terms were reviewed separately from the original installation. Oracle Cloud Free Tier FAQ

Pre Requisites:#

  1. Oracle Cloud Account
  2. Terraform installed (Official Guide)

Getting Required Oracle Keys and OCIDs#

Whether you’re using an Oracle client (see Software Development Kits and Command Line Interface) or a client you built yourself, you need to do the following:

  1. Create a user in IAM for the person or system who will be calling the API, and put that user in at least one IAM group with any desired permissions. See Adding Users. You can skip this if the user exists already.
  2. Get these items:
  3. Upload the public key from the key pair in the Console. See How to Upload the Public Key.
  4. If you’re using one of the Oracle SDKs or tools, supply the required credentials listed above in either a configuration file or a config object in the code. See SDK and CLI Configuration File. If you’re instead building your own client, see Request Signatures.

important

This key pair is not the SSH key that you use to access compute instances. See Security Credentials.

Both the private key and public key must be in PEM format (not SSH-RSA format). The public key in PEM format looks something like this:

text
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQE...
...
-----END PUBLIC KEY-----

How to Generate an API Signing Key#

You can use the following OpenSSL commands to generate the key pair in the required PEM format.

If you’re using Windows, you’ll need to install Git Bash for Windows and run the commands with that tool.

If you haven’t already, create a .oci directory to store the credentials: mkdir ~/.oci

Generate the private key with one of the following commands.

shell
openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 2048

Note: For Windows, you may need to insert passout stdin to be prompted for a passphrase. The prompt will just be the blinking cursor, with no text.

shell
openssl genrsa -out ~/.oci/oci_api_key.pem -aes128 -passout stdin 2048

To generate the key with no passphrase:

shell
openssl genrsa -out ~/.oci/oci_api_key.pem 2048

Ensure that only you can read the private key file:

shell
chmod go-rwx ~/.oci/oci_api_key.pem

Generate the public key:

shell
openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem

note

For Windows, if you generated the private key with a passphrase, you may need to insert passin stdin to be prompted for the passphrase. The prompt will just be the blinking cursor, with no text.

shell
openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem -passin stdin

Copy the contents of the public key to the clipboard using pbcopy, xclip or a similar tool (you’ll need to paste the value into the Console later). For example:

shell
cat ~/.oci/oci_api_key_public.pem | pbcopy

Your API requests will be signed with your private key, and Oracle will use the public key to verify the authenticity of the request. You must upload the public key to IAM (instructions below).

How to Get the Key’s Fingerprint#

You can get the key’s fingerprint with the following OpenSSL command. If you’re using Windows, you’ll need to install Git Bash for Windows and run the command with that tool.

shell
openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c

When you upload the public key in the Console, the fingerprint is also automatically displayed there. It looks something like this: 12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef

Where to Get the Tenancy’s OCID and User’s OCID#

Both OCIDs are in the Console, which is located at https://console.us-ashburn-1.oraclecloud.com.

If you don’t have a login and password for the Console, contact an administrator. If you’re not familiar with OCIDs, see Resource Identifiers.

Tenancy’s OCID#

Get the tenancy OCID from the Oracle Cloud InfrastructureConsole on the Tenancy Details page:

  1. Open the navigation menu, under Governance and Administration, go to Administration and click Tenancy Details.
  2. The tenancy OCID is shown under Tenancy Information. Click Copy to copy it to your clipboard.

User’s OCID#

Get the user’s OCID in the Console on the page showing the user’s details. To get to that page:

  • If you’re signed in as the user: Open the Profile menu () and click User Settings.
  • If you’re an administrator doing this for another user: Open the navigation menu. Under Governance and Administration, go to Identity and click Users. Select the user from the list.
  • The user OCID is shown under User Information. Click Copy to copy it to your clipboard.

How to Upload the Public Key#

You can upload the PEM public key in the Console, located at https://console.us-ashburn-1.oraclecloud.com.

  1. Open the Console, and sign in.
  2. View the details for the user who will be calling the API with the key pair:
    • If you’re signed in as the user: Open the Profile menu () and click User Settings.
    • If you’re an administrator doing this for another user: Open the navigation menu. Under Governance and Administration, go to Identity and click Users. Select the user from the list.
  3. Click Add Public Key.
  4. Paste the contents of the PEM public key in the dialog box and click Add.

The key’s fingerprint is displayed (for example, 12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef).

Notice that after you’ve uploaded your first public key, you can also use the UploadApiKey API operation to upload additional keys. You can have up to three API key pairs per user. In an API request, you specify the key’s fingerprint to indicate which key you’re using to sign the request.

Download and Configure WireHole#

Clone the repository with the following command

shell
$ git clone https://github.com/IAmStoxe/wirehole.git
$ cd wirehole
$ terraform init

Create a new file named terraform.tfvars and paste in the following

💡 **Replace necessary values -**Everything that’s above the optional banner.

If you don’t know where to get one of the values look at the section above this one.

hcl
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# Oracle Cloud Infrastructure Authentication details
# THIS IS NOT THE SAME AS YOUR NORMAL SSH KEY
# Replace with the fingerprint of your oracle key
oracle_api_key_fingerprint = "Xx:xX:Xx:xX:Xx:xX:Xx:xX:Xx:xX:Xx:xX:Xx:xX"

# Replace with the path to your private oracle key
oracle_api_private_key_path = "/home/ubuntu/.oci/oci_api_key.pem"

###################
# User OCID
user_ocid = "ocid1.user.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

###################
# Tenancy OCID
tenancy_ocid = "ocid1.tenancy.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

###################
# Compartment OCID
compartment_ocid = "ocid1.tenancy.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

###################
# Region
# List available: https://docs.cloud.oracle.com/en-us/iaas/Content/General/Concepts/regions.htm
region = "us-ashburn-1"

###################
# Your SSH Details used to access the server
# Fill in with your own public key signature
ssh_public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCybAAAAB3NzaC1yc2EAAAADAQABAAABAQCybAAAAB3NzaC1yc2EAAAADAQABAAABAQCybAAAAB3NzaC1yc2EAAAADAQABAAABAQCyb imported-openssh-key"

# Fill in the path to the private key of the ssh key
ssh_private_key_path = "/home/ubuntu/.ssh/id_rsa"


## Optional
# The display name of our new machine within Oracle's console
instance_display_name = "pihole-wireguard"

view raw gistfile1.txt hosted with ❤ by GitHub

Once you’re good to go test it out with

shell
$ terraform plan

If that completes without errors then you may proceed to the next section.

Deploying#

Now that we’re all configured the only thing left to do is to deploy.

So what is going to happen is:

  1. Terraform is going to create everything we defined in our code
  2. Once created, it will automatically SSH into the new server with your provided private key located atprivate_ssh_key_path and tail the cloud-init-output.log file to watch progress.

💡Within the output of the terminal will be QR codes you can (if you choose) to setup it WireGuard on your phone.

Once you see that all the docker containers are live and you see an output similar to that shown below press CTRL + C This will stop the remote-exec and now will output the requested information from outputs.tf

Modify your wireguard client configuring AllowedIps to 10.2.0.0/24 to only tunnel the web panel and DNS traffic.

Access PiHole Interface#

While connected to WireGuard, navigate to http://10.2.0.100/admin

The password (unless you set it in docker-compose.yml) is blank.

Pi Hole Admin Interface