BWS Examples

Examples of running various Gemini and web self-hosting services using Bubblewrapped Services on a server, e.g. VPS server or Raspberry Pi.

Example services

Here is a brief description for the example services:

• gemini-server: Molly Brown gemini server. The capsules are located in ~/gemini/, in a sub-folder matching the domain name. You can thus have multiple capsules hosted, and each can have CGI scripts in a cgi-bin sub-folder.
• http-server: Web server using althttpd which works simlarily to the gemini server above, with websites located in ~/www, also supporting CGI scripts.
• scm-fossil: Fossil source code hosting, a simpler alternative to using git. Simply copy your repo fossil file into ~/repos/fossil to get a hosted version.
• tcp-haproxy: HAProxy handles incoming traffic and routes them to the various backends. You can also add redirects, reverse proxies, load balancing, redirects, and much much more. Simpler to manage than nginx or Apache.
• ssl-certificates: Uses acme.sh to automatically issue and renew SSL certificates for your various backends. The certificates are used by the tcp-haproxy service.
• system-monitor: A very simple script to send an email alert if available RAM is below 50Mb, or available disk space for the home folder is less than 1.5Gb. Edit the ~/services/system-monitor/start.sh script to change the e-mail address and thresholds.
• gemini-comitium - RSS/gemini sub/webpage watcher feed aggregator
• gemini-kineto - A gemini to HTML gateway allowing you to view geminispace using a web browser.

Additional example services contributed by ~ew:

• finger-nanofingerd/
• gemini-satellite/
• gemring-cassini/
• gopher-gophrier/
• http-darkhttpd/
• nex-nexd/
• proxy-kinex/

Installation

To run these examples:

• Install Bubblewrapped Services into your server user's home directory.
• Check out this repo into your user's home directory. This will place the examples into the ~/services folder as well as adding folders in your user's home directory for Gemini capsules and Web sites.
• Some examples may require installation (they will have an install.sh you can run). Other examples don't include any binaries, but you can use the scripts under source to compile the binaries.
• Start the tcp-haproxy service to handle all of the incoming traffic to your server and route them to the correct backend. Note that in order to avoid running it as root, it listens for HTTP connections on port 8000, and HTTPS connections on port 8001. Use iptables rules to do the appropriate port forwarding, e.g. run the following script as root after every boot:

  #!/bin/sh
  IPT="/usr/sbin/iptables"
  $IPT -A PREROUTING -t nat -i eth0 -p tcp --dport 80 -j DNAT --to-destination :8000
  $IPT -A PREROUTING -t nat -i eth0 -p tcp --dport 443 -j DNAT --to-destination :8001
  

• Edit the ~/services/ssl-certificates/domains.txt file with the domains for your server.
• Install SSL certificates for your server domains by running ./services/bws test ssl-certificates. You can put this into a daily cronjob. You will need to restart the tcp-haproxy service if any certificates were updated.
• Some of the example services defaults to mydomain.tld as the server domain, so rename the folders or edit the configuration files to point to the correct names for your server.
• For the services you would like to start on boot, add them to ~/services/start.