Home

Awesome

Servus

alt text

About

Servus is a minimalist social media server fully self-contained within one executable file.

CMS

As a CMS, Servus sits somewhere in between Jekyll and WordPress.

Like Jekyll:

Unlike Jekyll:

Like WordPress:

Unlike WordPress:

Personal Nostr Relay & File server (Blossom & NIP-96)

If you already have a Nostr keypair, you already own your identity. But you only really own your data when you self-host it. Don't rely on other relays to store your data.

Blossom and NIP-96 are protocols adjacent to Nostr that specify how files (such as images) are to be stored on HTTP servers.

Features

Performance and limitations

The web is the social network!

The (perceived) performance for the visitors of web pages hosted using Servus is the most important.

As mentioned above, the web browser does not need to run any client-side code or make any additional requests to get the full experience! Plain HTML, CSS + any images, etc... It is also very easy to put a CDN in front of Servus and make requests even faster because of this very reason (static pages with no dependence on external requests)!

Servus does not aim to be a performant general-purpose Nostr relay - one that can efficiently ingest huge numbers of events, execute random queries or stream back events for subscriptions in real-time. There are others much better at that!

The Nostr relay offered by Servus is very limited! It should be fast to get all events belonging to a website... but it may be slow or even impossible to make more complex queries. Also, you don't get streaming of new events coming in after a query has been issued! After existing events are returned as response to a query, you get EOSE and the connection is closed. The client needs to open a new connection and make a new query later in the future if it wants to get new events.

Status

While Servus has quite a few features that may look like "advanced" and I use it personally to serve a couple of web sites, it is also still very much experimental and definitely not for everyone - especially not for beginners!

In order to use it, you need at least some basic understanding of:

You also need a VPS with SSH access where you would run Servus unless you are just curious and want to test it locally.

Also keep in mind that everything changes all the time without prior notice! So using it for a production website is very risky. For now...

Beginners

Does the above sound complicated to you?

You might want to stop here, bookmark this repo, and check back in a year.

Things are definitely going to improve, but for now I am too busy building a solid foundation in order to consider beginners. Sorry.

Themes

Servus currently supports Zola's Hyde theme. Some other Zola themes also work, some not.

Try it out

It's very simple to get up and running!

On Linux

This will work both locally and on a bare VPS (you can use its public IP address or DNS domain to access the site)!

On Windows or OSX

Windows and OSX builds are also available from the GitHub release page! Download, unzip and run it from a terminal.

Building from source

Usage

Note the sudo required to bind to port 443! Other ports can be used by passing -p, whether in SSL mode or not!

NB: in order to obtain Let's Encrypt certificates you must be running Servus on a machine that is accessible via a public IP (such as a VPS) and have the domain name mapped to that machine's IP. Running the --ssl-acme version on your developement machine won't work because Let's Encrypt will try to actually connect to your domain and validate your setup.

PS: You can try running the SSL version locally using a custom certificate by passing --ssl-cert and --ssl-key if you map 127.0.0.1 to your domain name from /etc/hosts and get a realistic simulation of the live environment on your local machine!

Directory structure

You can run the Servus executable from any directory. On start, it looks for a directory named themes and a directory named sites and loads all available themes and sites that it finds.

Themes are expected to be Zola themes.

A "site" is identified by the domain name, which is passed by the browser using the Host header.

.
├── themes
│   ├── hyde
│   ├── ...
│   └── ...
└── sites
    ├── domain1.com
    ├── domain2.com
    └── domain3.com

Each of these "sites" has the following structure:

├── _config.toml
├── _content
│   ├── data
│   │   ├── data1.yml
│   │   └── [...]
│   ├── notes
│   │   ├── note1.md
│   │   └── [...]
│   ├── pages
│   │   ├── page1.md
│   │   └── [...]
│   └── posts
│       ├── yyyy-mm-dd-post1.md
│       └── [...]
├── favicon.ico
└── [...]

Files and directories starting with "." are ignored.

Files and directories starting with "_" have special meaning: _config.toml, _content.

Anything else will be directly served to the clients requesting it.

_config.toml

Required: base_url, theme.

Optional: pubkey, title.

pubkey, if specified, is used to enable posting using the Nostr protocol. Only events from the specified pubkey will be accepted, after validating the signature.

Templating

Templating is handled by Tera, which should look familiar to anyone who has used Liquid or Jinja2. See Tera's documentation for more details.

Template variables

The following variables are passed to the templates:

Managing your content

Post to your site using any Nostr client such as Amethyst.

REST API

A simple REST API exists that can be used to create new sites and list sites associated with a Nostr pubkey.

/api/sites

A POST to /api/sites can be used to add a new site associated with a key.

A GET to /api/sites can be used to get a list of all the sites belonging to a key.

/api/config

A GET to /api/config will return the list of available themes and the currently selected theme.

A PUT to /api/config can be used to change the site's theme.

NB: All requests require a NIP-98 authorization header to be present!

Blossom API

Servus implements the Blossom API and therefore acts as your personal Blossom server.

NIP-96 API

Servus implements NIP-96 file storage.

Admin interface

The admin interface is rudimentary at best and lets you create sites and change a site's theme (using the Servus REST API). It requires you to have a Nostr extension such as Alby or nos2x installed in your browser. You might as well not use it and just change your site's theme by editing _config.toml and restarting Servus.

Any questions?

If you read this far without giving up and still want to try it yourself, feel free to open GitHub issues with any problems you encounter and I'll try to help!