Mensam

A desk-booking web application.

Public instance

mens.am

Are you hosting a coworking space, a hot-desk office or a community space like a hacker space?

Desks are a limited resource. Your members will be disappointed when they arrive at your location and realize there aren’t any desks available. Sometimes there are desks available, but a user has some special requirement like a power outlet or the user just wants to sit close to a window.

In these cases you probably want to set up a desk-booking solution like Mensam.

Usage

Setup

As the operator you simply visit an instance of Mensam, such as mens.am.

First you will have to create a User account for yourself. Now you create a new Space for your location. Within this Space you can now add Desks.

Join a Space

After creating a User account you can simply join a Space with a single click. Depending on the setup of the Space, it is listed publically or only accessible with a specific link.

Book a desk

After joining a Space you can create a Reservation for a Desk. You will be able to see other Reservations, so you can plan around them. Mensam will deny overlapping reservations.

Deployment

Docker

You can host a server using Docker. Docker Images are available on DockerHub.

Important

Make sure you are pulling an up-to-date version. Set up the configuration file. Use docker.json as a template configuration.

docker pull jumper149/mensam:v0.10.0.2
docker run --publish 8080:8177 --volume ./final/configurations/docker.json:/etc/mensam/mensam.json jumper149/mensam:v0.10.0.2

This will use the default configuration file for Docker deployments and now you should be able to visit the web interface on http://localhost:8080.

NixOS module

You can host a server by enabling it in your NixOS configuration.

{ config, pkgs, lib, ... }:
{
  services.mensam = {
    enable = true;
    config = {
      port = 8177;
      email-config = {
        hostname = "my-hostname.com";
        username = "[email protected]";
        password = "********";
      };
      base-url = {
        scheme = "https";
        authority = {
          host = "mensam.my-hostname.com";
          port= null;
        };
        path = [];
      };
    };
    environment = {
    };
  };

  services.nginx.enable = true;
  services.nginx.recommendedGzipSettings = true;
  services.nginx.virtualHosts."mensam.my-hostname.com" = {
    forceSSL = true;
    locations."/".proxyPass = "http://127.0.0.1:${toString config.services.mensam.config.port}";
    locations."/".extraConfig = ''
      add_header Cache-Control "no-store";
    '';
    extraConfig = ''
      error_page 501 502 503 /fallback.html;
      location = /fallback.html {
        root ${pkgs.mensam.full.fallback.outPath};
        add_header Cache-Control "no-store";
      }
    '';
  };
}

Development

Mensam is built with Nix. You can use regular flake commands such as nix build, nix develop or nix flake check.

Subflakes

The source code is split up into subflakes, which also have their own development environments and checks. These are just regular nix files, but follow the naming conventions of flakes.

Setup

Nix overlay

Server

HTTP API, Server executable, CLI-client executable

Frontend

Single page web application

Static

Static files served by the server

Final

Configuration, wrapper and NixOS module

Subflake dependency graph

  ┌──────────────────┐
  │                  │
  │           ┌──▶server
  │           │
  │     ┌── final
  │     │     │
  │     │     └──▶static──▶frontend
  │     ▼           │         │
  └──▶setup◀────────┘         │
        ▲                     │
        └─────────────────────┘

Development Container

VSCode supports devcontainers, which will allow you to quickly spin up a docker container with dependencies. Use the VSCode direnv extension to reload the dependencies.

Binary Cache

GitHub Actions pushes Nix results to Cachix. Use this binary cache to speed up your local builds.

Configure your NixOS configuration to trust the binary cache.

{
  nix.settings = {
    substituters = [
      "https://jumper149-mensam.cachix.org"
    ];
    trusted-public-keys = [
      "jumper149-mensam.cachix.org-1:9502wAOm00GdLxZM8uTE4goaBGCpHb+d1jUt3dhR8ZM="
    ];
  };
}

Versioning

Any version number EPOCH.MAJOR.MINOR.PATCH already tells the operator of a deployment some basic information.

EPOCH

Enormous changes. Read the changelog!

MAJOR

Major changes. These changes break backwards compatibility, often including database migrations.

MINOR

Minor changes. These changes are backwards compatible. API changes are also considered minor as the frontend is contained within the application.

PATCH

Bugfixes. These changes should always be applied as soon as possible.