</code></pre></div><p>By default, the webserver for the UI is listening on port <strong>8888</strong> on all available interfaces.</p><p>Volumes for <code>/app/data</code> and <code>/app/config</code> should be used ensure data persistence across container restarts.</p><h2id=wireguard-interface-handling>WireGuard Interface Handling</h2><p>WireGuard Portal supports managing WireGuard interfaces through three distinct deployment methods, providing flexibility based on your system architecture and operational preferences:</p><ul><li><p><strong>Directly on the host system</strong>: WireGuard Portal can control WireGuard interfaces natively on the host, without using containers. This setup is ideal for environments where direct access to system networking is preferred. To use this method, you need to set the network mode to <code>host</code> in your docker-compose.yml file. <divclass=highlight><pre><span></span><code><spanclass=nt>services</span><spanclass=p>:</span>
</code></pre></div></p><blockquote><p><imgalt=⚠class=twemojisrc=https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/26a0.svgtitle=:warning:> If host networking is used, the WireGuard Portal UI will be accessible on all the host's IP addresses if the listening address is set to <code>:8888</code> in the configuration file. To avoid this, you can bind the listening address to a specific IP address, for example, the loopback address (<code>127.0.0.1:8888</code>). It is also possible to deploy firewall rules to restrict access to the WireGuard Portal UI.</p></blockquote></li><li><p><strong>Within the WireGuard Portal Docker container</strong>: WireGuard interfaces can be managed directly from within the WireGuard Portal container itself. This is the recommended approach when running WireGuard Portal via Docker, as it encapsulates all functionality in a single, portable container without requiring a separate WireGuard host or image. <divclass=highlight><pre><span></span><code><spanclass=nt>services</span><spanclass=p>:</span>
<spanclass=w></span><spanclass=c1># WireGuard port, needs to match the port in wg-portal interface config (add one port mapping for each interface)</span>
</code></pre></div></p></li><li><p><strong>Via a separate Docker container</strong>: WireGuard Portal can interface with and control WireGuard running in another Docker container, such as the <ahref=https://docs.linuxserver.io/images/docker-wireguard/>linuxserver/wireguard</a> image. This method is useful in setups that already use <code>linuxserver/wireguard</code> or where you want to isolate the VPN backend from the portal frontend. For this, you need to set the network mode to <code>service:wireguard</code> in your docker-compose.yml file, <code>wireguard</code> is the service name of your WireGuard container. <divclass=highlight><pre><span></span><code><spanclass=nt>services</span><spanclass=p>:</span>
<spanclass=w></span><spanclass=nt>network_mode</span><spanclass=p>:</span><spanclass=w></span><spanclass=s>"service:wireguard"</span><spanclass=w></span><spanclass=c1># So we ensure to stay on the same network as the wireguard container.</span>
<spanclass=w></span><spanclass="p p-Indicator">-</span><spanclass=w></span><spanclass=s>"51820:51820/udp"</span><spanclass=w></span><spanclass=c1># WireGuard port, needs to match the port in wg-portal interface config</span>
<spanclass=w></span><spanclass="p p-Indicator">-</span><spanclass=w></span><spanclass=s>"8888:8888/tcp"</span><spanclass=w></span><spanclass=c1># Noticed that the port of the web UI is exposed in the wireguard container.</span>
<spanclass=w></span><spanclass="p p-Indicator">-</span><spanclass=w></span><spanclass="l l-Scalar l-Scalar-Plain">./wg/etc:/config/wg_confs</span><spanclass=w></span><spanclass=c1># We share the configuration (wgx.conf) between wg-portal and wireguard</span>
</code></pre></div> As the <code>linuxserver/wireguard</code> image uses <em>wg-quick</em> to manage the interfaces, you need to have at least the following configuration set for WireGuard Portal: <divclass=highlight><pre><span></span><code><spanclass=nt>core</span><spanclass=p>:</span>
<spanclass=w></span><spanclass=c1># The WireGuard container uses wg-quick to manage the WireGuard interfaces - this conflicts with WireGuard Portal during startup.</span>
<spanclass=w></span><spanclass=c1># To avoid this, we need to set the restore_state option to false so that wg-quick can create the interfaces.</span>
<spanclass=w></span><spanclass=c1># WireGuard Portal needs to export the WireGuard configuration as wg-quick config files so that the WireGuard container can use them.</span>
</code></pre></div></p></li></ul><h2id=image-versioning>Image Versioning</h2><p>All images are hosted on Docker Hub at <ahref=https://hub.docker.com/r/wgportal/wg-portal>https://hub.docker.com/r/wgportal/wg-portal</a> or in the <ahref=https://github.com/h44z/wg-portal/pkgs/container/wg-portal>GitHub Container Registry</a>.</p><p>Version <strong>2</strong> is the current stable release. Version <strong>1</strong> has moved to legacy status and is no longer recommended.</p><p>There are three types of tags in the repository:</p><h4id=semantic-versioned-tags>Semantic versioned tags</h4><p>For example, <code>2.0.0-rc.1</code> or <code>v2.0.0-rc.1</code>.</p><p>These are official releases of WireGuard Portal. For production deployments of WireGuard Portal, we strongly recommend using one of these versioned tags instead of the latest or canary tags.</p><p>There are different types of these tags:</p><ul><li>Major version tags: <code>v2</code> or <code>2</code>. These tags always refer to the latest image for WireGuard Portal version <strong>2</strong>.</li><li>Minor version tags: <code>v2.x</code> or <code>2.0</code>. These tags always refer to the latest image for WireGuard Portal version <strong>2.x</strong>.</li><li>Specific version tags (patch version): <code>v2.0.0</code> or <code>2.0.0</code>. These tags denote a very specific release. They correspond to the GitHub tags that we make, and you can see the release notes for them here: <ahref=https://github.com/h44z/wg-portal/releases>https://github.com/h44z/wg-portal/releases</a>. Once these tags for a specific version show up in the Docker repository, they will never change. </li></ul><h4id=the-latest-tag>The <code>latest</code> tag</h4><p>The lastest tag is the latest stable release of WireGuard Portal. For version <strong>2</strong>, this is the same as the <code>v2</code> tag.</p><h4id=the-master-tag>The <code>master</code> tag</h4><p>This is the most recent build to the main branch! It changes a lot and is very unstable.</p><p>We recommend that you don't use it except for development purposes or to test the latest features.</p><h2id=configuration>Configuration</h2><p>You can configure WireGuard Portal using a YAML configuration file. The filepath of the YAML configuration file defaults to <code>/app/config/config.yaml</code>. It is possible to override the configuration filepath using the environment variable <strong>WG_PORTAL_CONFIG</strong>.</p><p>By default, WireGuard Portal uses an SQLite database. The database is stored in <code>/app/data/sqlite.db</code>.</p><p>You should mount those directories as a volume:</p><ul><li><code>/app/data</code></li><li><code>/app/config</code></li></ul><p>A detailed description of the configuration options can be found <ahref=../../configuration/overview/>here</a>.</p><p>If you want to access configuration files in wg-quick format, you can mount the <code>/etc/wireguard</code> directory inside the container to a location of your choice. Also enable the <code>config_storage_path</code> option in the configuration file: <divclass=highlight><pre><span></span><code><spanclass=nt>advanced</span><spanclass=p>:</span>
