Web Backends¶
Using web backends you can connect your applications directly to our frontend to make them accessible from the outside. Traffic is proxied transparently to your application: WebSockets just work and the Host header is set correctly. If you have prior experience with RewriteRule proxies, you can also expect backends to be much faster.
Tip:
The application needs to listen on interface :: or 0.0.0.0 (using 127.0.0.1, localhost or ::1 does not work!) at any port between 1024 and 65535.
Warning:
If you make use of WebSockets, make sure to send [keep alive] packages every few minutes. Idle HTTP connections are shut down after three minutes.
In the background, every Asteroid gets its own virtual network interface. That enables you to use any port you like.
In order to use your own backend, you first need to set it up using the uberspace tool:
[isabell@moondust ~]$ uberspace web backend
Usage: uberspace web backend [OPTIONS] COMMAND [ARGS]...
Manage web backends
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ add Add web backend to existing Asteroid on this host. │
│ list List webbackends on this host. │
│ del Remove web backend from Asteroid on this host. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯Destinations¶
Every backend has a destination, which determines what handles requests to it:
| Destination | Handles requests with… |
|---|---|
APACHE |
Apache, serving PHP and static files from your DocumentRoot |
PORT |
your own application, listening on the given port |
STATIC |
Caddy directly, serving static files from your DocumentRoot without going through Apache/PHP-FPM |
Use STATIC for plain files (e.g. /assets) that don't need PHP processing – it skips the Apache/PHP-FPM stack entirely and is therefore faster.
List your backends¶
To list your backends use uberspace web backend list:
[isabell@moondust ~]$ uberspace web backend list
Domain Path Destination Port Prefix
─────────────────────────────────────────────
* / APACHE None keepThe default backend points to Apache.
no default backend?
If you removed your default backend you can restore it:
[isabell@moondust ~]$ uberspace web backend add / apache
OK: Added webbackend '/' to your AsteroidAdd a backend¶
To set the default backend to an application listening on port 1024 (for example your own nginx webserver) run:
[isabell@moondust ~]$ uberspace web backend add / port 1024 --force
OK: Added webbackend '/' to your Asteroid
[isabell@moondust ~]$ uberspace web backend list
Domain Path Destination Port Prefix
─────────────────────────────────────────────
* / PORT 1024 keepTip:
We use --force here because we need to overwrite the existing default backend.
specific path¶
Tip:
Note that by default, lots of apps aim to serve the app in the root folder. If a specific path is used in the web backend, then the app might need to be configured to serve from that folder. Alternatively, the app can be served using a subdomain, which does not require re-configuring the app itself.
In this example requests to /etherpad are routed to an application listening on port 9000, everything else is handled by apache:
[isabell@moondust ~]$ uberspace web backend add /etherpad port 9000
OK: Added webbackend '/etherpad' for '9000' to your Asteroid
[isabell@moondust ~]$ uberspace web backend list
Domain Path Destination Port Prefix
───────────────────────────────────────────────────
* / APACHE None keep
* /etherpad PORT 9000 keepSome applications don't serve assets due to performance reasons. In this example /assets is served via apache, everything else is routed to the application listening on port 9000:
[isabell@moondust ~]$ uberspace web backend add /assets apache
OK: Added webbackend '/assets' to your Asteroid
[isabell@moondust ~]$ uberspace web backend list
Domain Path Destination Port Prefix
──────────────────────────────────────────────────
* / PORT 9000 keep
* /assets APACHE None keepYou can also skip Apache/PHP-FPM entirely for plain files by using static instead:
[isabell@moondust ~]$ uberspace web backend add /assets static --force
OK: Added webbackend '/assets' to your Asteroid
[isabell@moondust ~]$ uberspace web backend list
Domain Path Destination Port Prefix
──────────────────────────────────────────────────
* / PORT 9000 keep
* /assets STATIC None keepmix and match¶
Of course you can combine specific paths and domains:
[isabell@moondust ~]$ uberspace web backend add example.de/assets port 1024
OK: Added webbackend 'example.de/assets' to your Asteroid[isabell@moondust ~]$ uberspace web backend list
Domain Path Destination Port Prefix
──────────────────────────────────────────────────────
* / APACHE None keep
example.de /assets PORT 1024 keepprefix handling¶
By default, the whole path (e.g. /etherpad/assets/style.css) is passed on to the backend. Some applications require that only the part after their prefix (/assets/style.css in this case) reaches them. To enable this behavior, add --remove-prefix.
Remove a backend¶
You can remove web backends with uberspace web backend del:
[isabell@moondust ~]$ uberspace web backend del /etherpad
OK: Removed web backend '/etherpad' from your Asteroid
[isabell@moondust ~]$ uberspace web backend list
Domain Path Destination Port Prefix
─────────────────────────────────────────────
* / APACHE None keep