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 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ set    Add web backend to existing Asteroid on this host.                                                                                  │
│ list   List webbackends on this host.                                                                                                      │
│ del    Remove web backend from Asteroid on this host.                                                                                      │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

List your backends

To list your backends use uberspace web backend list:

[isabell@moondust ~]$ uberspace web backend list

Domain   Path   Port   Transport
──────────────────────────────────
*        /      None   APACHE

The 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 Asteroid

Add 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   Port   Transport
──────────────────────────────────
*        /      1024   HTTP

Tip:

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        Port   Transport
 ───────────────────────────────────────
  *        /           None   APACHE
  *        /etherpad   9000   HTTP

Some 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      Port   Transport
─────────────────────────────────────
*        /         9000   HTTP
*        /assets   None   APACHE

mix 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      Port   Transport
 ─────────────────────────────────────────
  *            /         None   APACHE
  example.de   /assets   1024   HTTP

prefix 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   Port   Transport
──────────────────────────────────
*        /      None   APACHE