website

your user page is available at

• https://username.oss.zone
• https://oss.zone/~username

static sites#

files are served from the ~/public/html directory.

static site generators#

• zola - blazing fast static site generator in Rust
• hugo - world's fastest framework for building websites
• jekyll - simple, blog-aware, static sites
• mkdocs - project documentation with markdown

it's recommended to keep the source files for sites outside of ~/public/html.

CGI scripts#

the following file extensions are dynamically executed:

• .cgi - any interpreter
• .py - python
• .lua - lua
• .pl - perl
• .sh - shell

any files placed in ~/public/html/cgi-bin will be executed regardless of their extension. make sure you use #!/usr/bin/env <interpreter> as the shebang, make the script executable, and send the Content-Type header first.

you can also name a script index.cgi to handle all requests under a path:

• a request to /hurrycurry executes ~/public/html/hurrycurry/index.cgi
• a request to /man/chmod.1 executes ~/public/html/man/index.cgi with REQUEST_URI=/man/chmod.1

take a look at some CGI script examples if you need help.

UNIX sockets#

*-username.oss.zone is served over a UNIX socket at ~/public/http.sock, so you can run a reverse proxy like Caddy to host multiple domains or even services on your sub-domain.

basic example#

{
  admin off
  default_bind unix/{env.HOME}/public/http.sock|0666
}

http://test {
  respond "hi!"
}

http://ip {
  respond "{header.X-Forwarded-For}"
}

• admin off is set to prevent others from making changes to your configuration and to keep the port unused.
• default_bind makes all server directives listen on the specified UNIX socket. the permissions 0666 are required.
• requests to test-username.oss.zone will be rewritten to simply test before being passed to your server, to make requests simpler to handle.
• test-username.oss.zone will reply with a static message.
• ip-username.oss.zone will reply with your IP.

keeping it running#

you could just caddy run with a terminal multiplexer of your choice to keep the service running, but the best way is to create a systemd user service.

this service uses the Caddyfile in your home directory.

$ mkdir -p ~/.config/systemd/user

$ cat > ~/.config/systemd/user/caddy.service << EOF
[Service]
ExecStart=/run/current-system/sw/bin/caddy run --config %h/Caddyfile
Restart=on-failure
                                                                    
[Install]                                                 
WantedBy=default.target
EOF

$ systemctl --user daemon-reload
$ systemctl --user enable caddy --now