How to Install Subspace on Ubuntu server?

Posted June 9, 2020 9.2k views
Linux BasicsUbuntuNetworkingVPN

Subspace is a simple opensource WireGuard VPN server graphical user interface(GUI). You can install subspace directly on your server which would allow you to track and create client configurations.

Subspace is an open-source, self-hosted front end GUI (graphical user interface) for the Wireguard VPN system on the server-side. Once set up it provides a browser-accessible system to track clients and create client configurations for connecting to the server.

Some of the features of Subspace are:

  • WireGuard VPN Protocol.
  • Single Sign-On (SSO) with SAML.
  • Add new devices, connect from Mac OS X, Windows, Linux, Android, or iOS.
  • Remove Devices, removes client key, and disconnect clients.
  • Auto-generated Configs.

These answers are provided by our Community. If you find them useful, show some love by clicking the heart. If you run into issues leave a comment, or add your own answer to help others.

Submit an Answer
3 answers


In order to complete this guide, you will first need to perform the following tasks on your Ubuntu 18.04 Droplet:

Step 1 — Install WireGuard

First, update your existing list of packages:

  • sudo apt update

Add the WireGuard PPA to the system to configure access to the project’s packages:

  • sudo add-apt-repository -y ppa:wireguard/wireguard

Once the PPA has been added, update the local package index to pull down information about the newly available packages and then install the WireGuard kernel module and userland components:

  • sudo apt update
  • sudo apt install wireguard-dkms wireguard-tools

Remove dnsmasq because it will run inside the container:

  • sudo apt remove -y dnsmasq

Disable systemd-resolved if it blocks port 53.

  • sudo systemctl disable systemd-resolved
  • sudo systemctl stop systemd-resolved

After that setup CloudFlare as your DNS server:

echo nameserver | sudo tee /etc/resolv.conf

Step 2 — WireGuard modules

In order to load the required WireGuard modules you need to run the following commands:

  • sudo modprobe wireguard
  • sudo modprobe iptable_nat
  • sudo modprobe ip6table_nat

Once the modules have been enabled you need to run the following commands in order to enable the modules when the server gets rebooted:

  • echo "wireguard" | sudo tee /etc/modules-load.d/wireguard.conf
  • echo "iptable_nat" | sudo tee /etc/modules-load.d/iptable_nat.conf
  • echo "ip6table_nat" | sudo tee /etc/modules-load.d/ip6table_nat.conf

Finally check if systemd-modules-load service is active:

sudo systemctl status systemd-modules-load.service

Step 3 - Enable packet Packet forwarding

In order to get WireGuired to work as expected, we need to make sure that package forwarding is enabled. Packet forwarding means allowing packets to go from one network to another.

To do that you need to run the following commands:

  • sudo sysctl -w net.ipv4.ip_forward=1
  • sudo sysctl -w net.ipv6.conf.all.forwarding=1

Step 4 - Configure Domain name DNS

In order to use Let’s Encrypt and secure our Subspace instance, we need to make sure that we have a domain name that points to our Droplet’s IP address.

To do that make sure to create a DNS A record for your domain or subdomain name and point it to your server’s IP address.

Example: A

Step 5 - Firewall Rules

As subspace runs a TLS (“SSL”) https server on port 443/tcp and a standard web server on port 80/tcp, we need to make sure that the two ports are open for incoming TCP traffic via our firewall. To do that run the following commands

  • sudo ufw allow 80
  • sudo ufw allow 443

Also, as port 51820/udp is the default WireGurad port, we need to make sure that it is open as well:

  • sudo ufw allow 51820/udp

Next, we need to start the subspace Docker container.

Step 6 - Start subspace

Your data directory should be bind-mounted as /data inside the container using the --volume flag.

  • sudo mkdir /data

After that, we need to create our container. Make sure to change the --env SUBSPACE_HTTP_HOST to your domain name which is pointing to your Droplet.

docker create \
    --name subspace \
    --restart always \
    --network host \
    --cap-add NET_ADMIN \
    --volume /usr/bin/wg:/usr/bin/wg \
    --volume /data:/data \
    --volume /lib/x86_64-linux-gnu/ \
    --volume /lib64/ \
    --env SUBSPACE_HTTP_HOST="" \

Then start your container:

  • sudo docker start subspace

You can also check the logs of your container to make sure that it starts as expected:

  • sudo docker logs subspace

Then visit your domain name via your browser and you will be able to see your subspace installation!


The subspacecommunity/subspace project is community maintained and is a fork of the simple WireGuard VPN server GUI. If you notice any problems feel free to submit an issue or a pull request!

Hope that this helps!

by Justin Ellingwood
by Erika Heidi
This guide will walk you through a few procedures that you should take early on in order to create a solid foundation for your new Ubuntu 18.04 server, before moving on to installing and configuring any software or services.
  • Hi Bobby,

    I noticed that the DNS A record for to the server has a private IP address (Step 4). Will the SSL still work if it’s pointed to a public IP address which is then forwarded to the private IP?

    That is the setup I am currently trying but I’m getting an SSL internal error.

    • Hi there @whizzard,

      I would recommend using the public IP so that Let’s Encrypt could validate your domain name.

      Let me know how it goes!

      • Is it possible to do this without the the SSL?

        • Hi there @whizzard,

          I have not tested it without an SSL certificate, but if you don’t have a domain name that you could use, I could suggest using Freenom and getting a free domain name for 1 year.

          Then you can point the domina name to your DigitalOcean Droplet and issue a Let’s Encrypt certificate.

          You can follow the steps on how to do that here.


  • Hey there,

    I am using traefik for reverse proxy for all my containers, could I use the subspace container without SSL considering that I will use https from traefik to secure the wireguard gui ?


That’s what I used but I keep getting a “ERRSSLPROTOCOL_ERROR” or

“*Secure Connection Failed

An error occurred during a connection to Peer reports it experienced an internal error.


The page you are trying to view cannot be shown because the authenticity of the received data could not be verified.
Please contact the website owners to inform them of this problem.*"

Depending on browser used.

  • Hi there @whizzard,

    Have you tried checking the docker container logs for more information on what the actual error is? To do so run the following command:

    • docker logs container_id


    • I am seeing a repeat of errors like this:

      2020/08/16 20:02:44 http: TLS handshake error from autocert: host “” not permitted by HostPolicy
      2020/08/16 20:04:33 http: TLS handshake error from acme/autocert: missing server name
      2020/08/16 20:15:24 http: TLS handshake error from acme/autocert: missing server name
      2020/08/16 20:30:44 http: TLS handshake error from autocert: host “ (publicIPaddress)” not permitted by HostPolicy
      2020/08/16 20:44:37 http: TLS handshake error from acme/autocert: missing server name
      2020/08/16 20:57:49 http: TLS handshake error from tls: first record does not look like a TLS handshake
      2020/08/16 21:46:25 http: TLS handshake error from acme/autocert: missing server name
      2020/08/16 23:17:46 http: TLS handshake error from tls: unsupported SSLv2 handshake received
      2020/08/17 00:02:24 http: TLS handshake error from EOF
      2020/08/17 00:02:45 http: TLS handshake error from acme/autocert: unable to satisfy “” for domain “”: no viable challenge type found
      2020/08/17 00:02:45 http: TLS handshake error from autocert: host “
      IP_address)” not permitted by HostPolicy
      2020/08/17 01:50:40 http: TLS handshake error from acme/autocert: missing server name

403 urn:acme:error:unauthorized: Account creation on ACMEv1 is disabled. Please upgrade your ACME client to a version that supports ACMEv2 / RFC 8555. See for details.

someone forgot to update subspace ACME client…

  • Hi @mythnick,

    Are you using subspacecommunity/subspace:latest? I think this is fixed for the latest subspace community version.

    Note that the official subspace project is no longer maintained and the subspacecommunity is the maintained fork.


      • Hi @mythnick,

        No problem, happy to help! I actually hit the same issue the first time I was setting this up.


        • Hello,

          Thanks for great tutorial.

          I already login in, and created several clients,

          here is UFW status

          root@localhost:~# sudo ufw status
          Status: active
          To                         Action      From
          --                         ------      ----
          80                         ALLOW       Anywhere                  
          443                        ALLOW       Anywhere                  
          51820/udp                  ALLOW       Anywhere                  
          80 (v6)                    ALLOW       Anywhere (v6)             
          443 (v6)                   ALLOW       Anywhere (v6)             
          51820/udp (v6)             ALLOW       Anywhere (v6

          and wg show:

          wg0 and peers that I created at

          After import peers into my Mac, iPhone… only data sent, but no received, what did I missed please?