Fenrus: a self-hosted home page that can read data back from your apps

Four kinds of shortcut, and only the last two are interesting

The configuration model is groups holding applications, links and other dashboards, and within that there are four shortcut types. Links are basic links to websites, either internal or external, showing no extra information, and you can configure an icon, or if left blank Fenrus will try to download the favicon for the site. Apps, Basic are a step above links, known to Fenrus, with a high-resolution icon, perhaps a default URL, but little else. Apps, Smart are where the project says the magic really happens: these have extra information that Fenrus can download and query to display more information about the app, which could be something as simple as basic information or a feature-rich experience. Dashboards link to other dashboards, and can be added to a group or reached through the drop down menu at the top of the page. The distinction between Basic and Smart is the design: Basic is a tile with a good icon, Smart is a tile that talks to the service behind it.

Everything lives in one encrypted LiteDB file

All configuration is saved into a LiteDB file called Fenrus.db, and there is an encryption key alongside this database file used to encrypt sensitive data inside the database. The stated reason is practical: if you need to provide the database for support reasons, your sensitive data cannot be read. That is a reasonable design for a self-hosted app that might hold credentials for the services it links to, and it means the backup you copy off the host is not a plaintext dump of your saved tokens. In the container, all the user configuration data is saved in the folder /app/data, so that folder has to be mapped outside the container or the data is lost on the next run. The repository tree shows the shape of the project, with Controllers, Models, Views, Services, Middleware, Components, Apps, Workers, Terminals, an Upgrades directory and an i18n folder, and the entry point is Program.cs with the project file Fenrus.csproj and a solution file alongside.

Running it is one docker run, and the volume is the part that matters

Docker is the preferred method of installing Fenrus, and the command is short:

docker run -d \
--name=Fenrus \
-e TZ=Pacific/Auckland \
-p 3000:3000 \
-v /path/to/data:/app/data \
--restart unless-stopped \
revenz/fenrus:latest

The port is 3000 by default and can be changed with the Port environment variable, and the timezone is set through TZ in the same way. A compose equivalent is provided too, with the same image, volume, port mapping and restart policy. The Dockerfile behind this is a thin wrapper around the ASP.NET Core 10.0 runtime image, with the application files and the Apps directory copied in, the reset.sh and docker-entrypoint.sh scripts made executable, and a symlink created so that /bin/sh points at bash. The environment note is worth repeating because it is the one setting people get wrong: the /app/data volume is where the database lives, and without it every container restart is a fresh install.

Without Docker it is a .NET runtime and one command

Fenrus is a Dotnet application and requires the ASP.NET Core Runtime to run. Running it directly is:

dotnet Fenrus.dll

and you can specify a port with the --urls argument:

dotnet Fenrus.dll --urls=http://*:1234

That --urls form is the standard ASP.NET Core hosting option rather than something specific to Fenrus, which is a useful signal about how the project is built. It is a conventional ASP.NET Core application with a Razor Pages and MVC style layout, which means the deployment story is the one your hosting already supports rather than a bespoke one.

Reverse proxy settings are nine environment variables

If you want to host Fenrus behind a ReverseProxy in combination with oauth authentication, you need to make sure that you are passing X-Forwarded-Proto and X-Forwarded-For headers from your reverse proxy to Fenrus, and Fenrus will use these headers to generate the correct urls for oauth authentication. The settings are configured through a table of environment variables. ReverseProxySettings__UseForwardedHeaders enables reverse proxy support and negates all the settings below it, defaulting to false. ReverseProxySettings__DebugPrintRequestHeaders prints request headers to the console so you can verify the forwarded headers are present, which is the diagnostic you want first. ReverseProxySettings__KnownProxies is a string array of trusted proxy IP addresses, empty by default. The last six variables configure a known IPv4 network and a known IPv6 network, each with an Enabled flag, an IpAddress and a PrefixLength, both networks enabled by default.

Registration is open until you turn it off

The Getting Started section is short. You need to register a user, which you do on the login page by entering a username and password and clicking Register if no user with that username exists, in which case a new one is created. The first user created in the system is automatically assigned the admin role, and that role allows the user to manage other users. The FAQ makes the consequence explicit: there is no default user, and entering a username and password then clicking the Register button creates a new administrator user, after which you can go to System and turn off registrations if you do not wish to allow open registrations. That is the right default for a personal app exposed on a network, and it is also the one piece of setup that is easy to forget and awkward to recover from, because the person who registers first owns the instance.

Search engines are configured, not hard-coded

The last configurable piece is the search engines, which are defined with four fields: the Name, which is the name of the search engine, the URL for the search query with %s being replaced by the search term, the Shortcut to type to use this search engine if it is not the default, and the Icon to show when using the engine. Defining them as data rather than baking them in is the right call for a personal tool, since the set of search engines a person uses is a matter of taste and changes. The repository also carries a Terminals directory and an Upgrades directory alongside the main application folders, which suggests the project keeps a notion of schema migrations for its own database, and a Globs.cs and Globals.cs at the root for the settings that the application treats as global.

Editorial conclusion

Adopt Fenrus if you want a personal start page that runs on your own hardware and can show live information from the services you use, rather than a static bookmark list. Do not adopt it if you need a multi-user product, because the first registered user becomes the administrator and the model is explicitly a personal home page. Before you commit, map a volume for the app data directory so the LiteDB file survives a container rebuild, and if you plan to put it behind an authenticating reverse proxy, set the ReverseProxySettings variables before the first login rather than after.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. revenz/Fenrus on GitHub