# linuxserver/reverse-proxy-confs for SWAG reverse proxy setup

> linuxserver/reverse-proxy-confs supplies sample NGINX configurations for exposing containerized applications through the LinuxServer SWAG image. It is aimed at Docker users who need subdomain routing, while requiring shared networking and per-application adjustments in some cases.

**linuxserver/reverse-proxy-confs** — These confs are pulled into our SWAG image: https://github.com/linuxserver/docker-swag

- Repository: https://github.com/linuxserver/reverse-proxy-confs
- Stars: 1,632 · Forks: 325
- Language: Unknown
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/linuxserver-reverse-proxy-confs

## Where reverse-proxy-confs fits in a SWAG deployment

This repository does not provide a standalone proxy server. It supplies sample reverse proxy configuration files that are pulled into the SWAG image maintained through the linked linuxserver/docker-swag project. The intended user is already running SWAG in Docker and wants to place an application behind its NGINX setup.

The repository focuses on commonly used applications and LinuxServer-provided Docker images. It explicitly excludes samples that publicly expose server management software such as Synology, QNAP, Unraid, Proxmox, and ESXi. Pull requests for that category are not accepted. This boundary matters for administrators because the collection is not intended to become a catalog of ingress configurations for every administrative interface.

The files are organized around two URL models. A subdomain configuration exposes a service at a host such as `https://servicename.yourdomain.com`, while a subfolder configuration places it under a path such as `https://yourdomain.com/servicename`. The README recommends subdomain proxying. Its reason is architectural rather than cosmetic: path-based routing often depends on the application producing links and redirects that include the correct base path, and many applications provide no support or only partial support for that requirement.

This makes the repository most useful as an integration catalog for SWAG. It reduces the need to design an NGINX location, proxy headers, and upstream hostname from scratch for each container. It does not, however, turn the target application into a production-ready Internet service. Public exposure still requires correct networking, application configuration, and decisions about which services should be accessible.

## How the .sample files reach the SWAG NGINX configuration

The repository keeps configurations as `.sample` files so they are not activated merely because they exist in the source collection. To use one, the administrator adds the appropriate include directive to the default site configuration, renames the selected file by removing `.sample`, and restarts SWAG.

The default site must include either the subfolder group or the subdomain group. The documented directives are:

```nginx
include /config/nginx/proxy-confs/*.subfolder.conf;
include /config/nginx/proxy-confs/*.subdomain.conf;
```

The first directive loads only active subfolder files. The second loads active subdomain files. Because the wildcard patterns exclude the `.sample` suffix, an untouched sample remains inactive.

The selected file then determines how SWAG routes requests to an upstream container. The repository description and README establish that the upstream is addressed through a Docker DNS hostname that normally defaults to the container name. For example, a sample named for a particular service is expected to correspond with that service's container name unless its configuration says otherwise.

This mechanism depends on where the SWAG image places these files under `/config/nginx/proxy-confs`. The linked docker-swag repository is the distribution source, while this repository is the source for the proxy configuration samples. A user should not expect cloning this repository alone to activate files inside an already running SWAG container.

## Preparing the shared Docker network for upstream DNS

The most important infrastructure requirement is not visible in the file names. SWAG must resolve the proxied container through Docker's internal DNS, and the documentation expects both containers to be attached to the same user-defined Docker bridge network.

For containers defined in the same `docker-compose` YAML file, the README states that Docker Compose creates a custom network and attaches the containers automatically. In that case, no extra network declaration is required according to the project's instructions. This makes a compose-based deployment the shortest documented path.

When containers are created from the command line, the documented sequence is to create a bridge network and pass its name through the container create or run configuration:

```bash
docker network create [networkname]
```

The network name must then be supplied using the documented `--network [networkname]` option. Portainer and Unraid are also covered by the README. Portainer can create a custom bridge network and attach containers through its interface. For Unraid, the README says to create the network and set `Preserve user defined networks:` to `Yes` before selecting the custom network for SWAG and each relevant service container.

A DNS failure therefore does not necessarily indicate an NGINX syntax error. If the target is unreachable by its expected hostname, or if it runs on another machine, the documentation says that the proxy configurations must be modified for the deployment. The repository does not provide a generic remote-host setup procedure.

## Activating a subdomain sample through the SWAG container

A first deployment can follow the documented control flow: add the include for the URL style, place the repository files where the SWAG image expects them, attach SWAG and the target container to a shared network, activate one sample, make any application changes named by that file, and restart SWAG.

Start by adding the subdomain include in the appropriate position of the default site configuration:

```nginx
include /config/nginx/proxy-confs/*.subdomain.conf;
```

Then create the custom network if the deployment does not already have one:

```bash
docker network create [networkname]
```

Attach both containers to that network through their creation or run settings. The exact full container run commands are not documented in this repository, so they are intentionally omitted here.

Choose the sample matching the application, remove `.sample` from its filename, and restart SWAG. The README gives this filename pattern:

```bash
sonarr.subfolder.conf
```

That example illustrates the rename operation rather than a complete command. For a subdomain deployment, the active filename would use the matching `.subdomain.conf.sample` source and end as `.subdomain.conf` after renaming.

Before restarting, inspect the first line of the chosen configuration. The README says each file lists required service-container changes there. Applications may need a base URL or another setting aligned with the external path or host. LinuxServer containers installed on the same host with the recommended options are said not to require edits to the sample itself in many cases, but this is conditional on the deployment matching those options.

After the restart, the documented expectation is that the selected host reaches its service through the SWAG endpoint. The README does not define health-check commands, log inspection steps, or a formal verification procedure.

## Why subfolder routing creates application-level work

Subdomain routing places each application at the root of its own host. Relative application URLs can therefore remain consistent without every upstream project adding support for an extra URL prefix. The README recommends this approach because it does not require special accommodation from application developers.

Subfolder routing uses `https://yourdomain.com/servicename`. That is attractive when separate hostnames are inconvenient, but it moves responsibility to the application. Links, redirects, forms, assets, and generated callbacks must remain under the configured path. If an application emits root-relative URLs, requests can escape to the domain root and target the wrong route or service.

The repository includes both styles for some listed applications, including Audiobookshelf, Adminer, Airsonic, Azarr, and others visible in the top-level entries. Availability of a subfolder sample does not guarantee complete behavior inside that application. The README specifically warns that support may be absent or partial and calls the result unreliable in such cases.

Subdomain routing also has an operational requirement: the DNS and host naming plan must include every service host. The supplied documentation explains the routing trade-off but does not provide wildcard DNS instructions. Administrators choosing subfolders should therefore inspect each target application's base URL behavior before selecting that route.

## Repository scope, maintenance signals, and license obligations

Based on the repository layout, this is a collection of NGINX sample files and templates rather than an application with a command-line interface, release package, or independent runtime. There are no GitHub releases, so upgrading does not follow a documented tagged release channel. Changes arrive through repository updates, while each user handles copying, enabling, modifying, and removing configurations inside SWAG.

The last push was on 2026-07-22. The repository is not archived. The available evidence supports current repository activity, although the project provides no published service-level policy or compatibility matrix.

The repository is identified under `GPL-3.0`. That license identifier affects how the repository's code may be distributed and modified under its terms. This review does not interpret the license or provide legal advice. The operational upgrade cost is mainly configuration review: an administrator must compare changed samples with locally modified files, preserve required application settings, and retest routing after restarting SWAG. The README does not document automated merging, conflict resolution, or rollback for customized files.

The practical alternative is a hand-written SWAG or NGINX configuration. That route avoids copying a sample whose assumptions do not match the service, but it shifts all work for proxy headers, upstream naming, path handling, and application-specific changes to the administrator. The sample repository is useful when its documented conventions fit the deployment; handwritten configuration is preferable when remote hosts, unusual paths, authentication behavior, or substantial customization make editing a shared sample harder to track.

## Removing an active sample without affecting the source collection

Disabling a configuration is straightforward according to the README: delete the active configuration and restart SWAG. Deletion applies inside the deployed SWAG configuration, not to the upstream repository. Since activation requires removing `.sample` from the local filename, the source collection can remain unchanged while a selected file is copied into the active set.

For a subfolder deployment, the default site loads files matching `*.subfolder.conf`. Removing an active file prevents that file from contributing after the restart. Administrators should also check whether the target application retains a base URL or path setting configured solely for the proxy. The README explains that some applications require matching changes, but it does not say that deleting the proxy file automatically reverses those settings.

The repository does not document a transactional reload or rollback sequence. It directs users to restart SWAG after enabling or deleting configurations. That simplicity is appropriate for a sample repository, but local copies and application settings must be tracked separately if the deployment needs repeatable recovery.

## Conclusion

Adopt this repository when you already run SWAG and want a documented starting point for reverse proxying a supported container. Do not treat the samples as a general proxy-management system or assume every application supports subfolder paths. Before enabling a configuration, verify that the SWAG container and the target service share a user-defined Docker network, inspect the application-specific instructions on the first line of the selected file, and confirm that its own settings match the route in that file.

## FAQ

### How do I activate a reverse proxy configuration in linuxserver/reverse-proxy-confs?

Add the relevant wildcard include to the SWAG default site configuration, rename the selected file by removing `.sample`, make any application changes listed on its first line, and restart SWAG.

### Why can SWAG not reach the reverse proxied container?

The configurations assume both containers are attached to the same user-defined Docker bridge network so Docker DNS can resolve the service container name. The README says the configuration must be modified if the service is unreachable by DNS or runs on another machine.

### Should linuxserver/reverse-proxy-confs use subdomains or subfolder paths?

The README recommends subdomains because applications do not generally need to add support for a URL prefix. Subfolder routing is listed for convenience, but the documentation warns that applications often provide no support or only partial support.

## Sources

- [Issues](https://github.com/linuxserver/reverse-proxy-confs/issues)
- [License: GPL-3.0](https://github.com/linuxserver/reverse-proxy-confs/blob/master/LICENSE)
- [linuxserver/reverse-proxy-confs on GitHub](https://github.com/linuxserver/reverse-proxy-confs)
- [README](https://github.com/linuxserver/reverse-proxy-confs/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/linuxserver-reverse-proxy-confs