Log in to your domain name provider, and add/modify the host DNS records for both the base domain as well as a wildcard for any subdomains. Ensure to do this on a clean and unused domain (unless you know what you're doing). Depending on the provider, there are different terms used. Here are some tips on where to access/modify the DNS for the four providers shown on the Requirements page:
| Type | Name | Value |
|---|---|---|
| A | @ | 123.45.67.89 |
| A | * | 123.45.67.89 |
Point these to the IP address of your RelayServer, i.e. replace 123.45.67.89 with your RelayServer's IP address. You will also need to add more DNS records for email, so keep this handy during the installation process. You can delete any other preexisting A, MX, CNAME, or TXT records that may have been created by your domain name provider. Just ensure that you do NOT edit/delete the nameserver records (they are likely in a different area of the web portal).
Depending on domain name provider, you might have to use the base domain name instead of using just the @ symbol. The @ symbol is a shorthand for the base domain (also referred to as a "naked domain"). Furthermore, this applies likewise with the wildcard character (*). So, if you cannot simply enter the @ symbol, then use your base domain, such as example.com, and for the wildcard, use *.example.com instead of just the * character.
See Other Software > SSH Terminal in Requirements for SSH terminal application options.
From the linux terminal of your HomeServer, first download the script using the following command:
wget -qN4 https://homeserverhq.com/hshq.sh
If you wish to verify the source code before proceeding, see this page: Verify Source Code
Then, to run the script, enter:
bash hshq.sh
Select Perform Base Installation from the menu, and follow the instructions accordingly. Once the configuration has been prepared, you will be instructed to type 'install' to perform the installation. Before entering this, ensure you copy the indicated section and paste it to a text file for further use during the installation process.
To copy text within the terminal window, simply select the text with your mouse and it will automatically be copied to the clipboard.
After starting the installation process, you may want to view the progress on the RelaySever. To do this, login to the RelayServer via SSH with the newly created username. Then enter the command:
screen -r hshqInstallOn both HomeServer and RelayServer, the operating systems will be restarted once the installation process has completed. Ensure you update the SSH port to the newly chosen port for any subsequent ssh logins (the new port will not take effect until after the server has restarted).
If you selected a desktop GUI to be installed, be prepared for a much longer time to install.
Review the installation configuration text file for your specific email DNS records, but they should look similar to the table below. Replace example.com with your domain name. Ensure to see note in blue info box in Setup DNS section at the top of this page regarding the @ and * symbols.
You will not be able to add the last item until you have generated the dkim key inside the mail admin web utility. This is not available until the base installation has completed. (See Item 3 in Post-Installation)
1Ensure you replace YourDomainKey correctly
If you have the capabilities with your RelayServer VPS provider to modify your DNS PTR record, also known as the Reverse DNS record, then ensure to change that as well. The PTR/Reverse DNS record is the opposite of a traditional DNS lookup - it resolves the name from the IP address. It's important to at least investigate this, as you could possibly adopt the previous IP address owner's setting (which has happened to someone before). An incorrect setting for this can cause email receipt issues, as the value could get translated into the HELO command, and thus cause the receiving SMTP instance to potentially reject it (another RelayServer instance will, since the Postfix instance is configured to reject it). To change this, search through your VPS provider's settings for DNS PTR record or Reverse DNS record, They may not offer the ability to change it, only some allow it. Take note that this is with your VPS provider for your RelayServer, not your domain name provider.
Download WireGuard for your current device (https://www.wireguard.com/install/). In bottom left of WireGuard utility window, press the down arrow next to Add Tunnel and select Add Empty Tunnel. Copy and paste the User WireGuard Configuration section from your installation configuration text file. Provide a name for your configuration and save it.
If you are using a made-up domain name, then you MUST replace the Endpoint subdomain with the actual IP address of the RelayServer within the WireGuard configuration. This is the second to last line of the configuration, it should look like: Endpoint = wg.external.example.com:51821. Replacing the name with the IP address, it should then look like this: Endpoint = 123.45.67.89:51821. Only replace the name portion (wg.external.example.com), ensure it still ends with :51821
If your HomeServer is being installed at home on your local home network, then you can safely activate this once the RelayServer has installed and rebooted. If you are installing your HomeServer on a remote VPS (e.g. for testing), then wait until the HomeServer has fully installed and rebooted, otherwise you will interrupt your SSH connection while the installation is running. Disable any other VPN software before activating your connection.
Once the connection has been activated, go to https://www.whatismyip.net/ and your masqueraded IP address should match your RelayServer's IP address. All of your internet traffic for that device will be routed through your RelayServer.
You will need to install your Root CA public certificate on any device that will be accessing your private network. It only needs to be done once per device and the certificate is good for more than 20 years.
After the HomeServer installation has completed and the system has restarted, copy and paste the Root CA URL (first line of your configuration text file) into your browser address bar. You might need to wait a few minutes after the system has restarted.
Note that the URL is http and not https. Most if not all modern browsers will automatically redirect http to https if the http url is not found (i.e. service isn't available yet). Without clearing the cache and restarting the browser entirely, it will continue to redirect to https even after the service is up and you will not be able to download the certificate. If you have a different browser, it might be easier to use that. Also, try disabling then re-enabling your WireGuard VPN connection, as this will refresh the DNS lookup.
After pasting the link, it should prompt you to download the certificate. Locate the downloaded file, then double-click it to initiate the certificate installation process. Select Install Certificate, then Current User (or Local Machine for all users), then select Place all certificates in the following store, then click Browse, then select Trusted Root Certification Authorities, then Next, then Finish.
Open Keychain Access manager. Navigate to File > Import Items. Browse to the example.com-ca.crt file (replace example.com with your domain name) and open it. Select System from the Keychain drop-down and click Add. Double-click on certificate and select Trust drop down arrow. Select Always Trust in When using this certificate section.
You must use Safari browser to install the certificate via the Root CA URL. Then, confirm you want to allow the download of the profile. If using Apple Watch, select iPhone when prompted. Then open Settings, go to General > VPN & Device Management to see your profiles, tap on your certificate, then Install. Then, go to Settings > General > About > Certificate Trust Settings, and toggle enable under ENABLE FULL TRUST FOR ROOT CERTIFICATES for your certificate.
Put certificate in /usr/local/share/ca-certificates. Then enter sudo update-ca-certificates at command line. Certain browsers such as Firefox and Chromium-based (Brave, Vivaldi, etc.) have their own certificate trust stores and thus certificates must be manually added into their respective stores.
Click on the certificate .crt file once downloaded. It should provide the necessary prompts to install the certificate. To load it manually, go to Settings > Biometrics and security > Other security settings > Install from device storage, and select the downloaded certificate to initiate the installation.