docs(administration): initial scaffolding

docs/administration.md

@@ -1,3 +1,77 @@
 # Administration
 
-Work in progress.
+## Overview
+
+This document provides an overview of the administration tasks and responsibilities for managing the
+system. It includes guidelines for user management, system configuration, and maintenance tasks.
+
+Interactions with the server are done through the `dsfxctl` command line tool, which allows administrators
+to perform various operations with their system.
+
+---
+
+## dsfxctl
+
+### Installation
+
+To install the `dsfxctl` command line tool, we recommend using the standard go toolchain to install
+the latest version of the tool. You can do this by running the following command:
+
+```bash
+go install koti.casa/numenor-labs/dsfx/cmd/dsfxctl@latest
+```
+
+### Configuration
+
+The first time you run the `dsfxctl` command, it will create a configuration directory to store
+the necessary files for the tool to function properly. By default, this directory is located in the
+`/etc/dsfxctl`, but this can be overridden by setting the `DSFXCTL_CONFIG_DIR` environment variable
+to a different path. We recommend configuring a path in your home directory so that the command
+can be run without root privileges. For example, you can set the environment variable to point
+to a directory in your home directory, such as `~/.config/dsfxctl`.
+
+```bash
+export DSFXCTL_CONFIG_DIR=~/.config/dsfxctl
+```
+
+### Identity
+
+The `dsfxctl` command requires a user identity to perform operations. This identity is specified
+by the `ed25519.key` file in the configuration directory. The key file should contain a valid
+ed25519 private key encoded in base64. The server application will use this key to sign requests and
+authenticate the user. If the key file is not present, which is the case when you first run the command,
+the server will generate a new key pair and store it in the `ed25519.key` file. This file is stored
+unencrypted, so it is important to ensure that the permissions on this file are set correctly to
+prevent unauthorized access. We recommend setting the permissions to `0600` to restrict access
+to the owner only. You can do this by running the following command:
+
+```bash
+chmod 0600 ~/.config/dsfxctl/ed25519.key
+```
+
+In the future we will explore options for encrypting the key at rest, or using a hardware security
+module (HSM) to manage the key securely.
+
+To view the identity associated with the `dsfxctl` command, you can run the following command:
+
+```bash
+dsfxctl identity
+```
+
+This will display the base64 encoded public key associated with the private key in the `ed25519.key` file.
+
+### Admin Registration
+
+Admin registration is performed similar to authorized ssh users. The server application initializes a
+file in the config directory called `admins`. This file contains a list of base64 encoded public keys
+for each admin user. The server will check this file to determine if a user is authorized to perform
+administrative tasks. Keys are separated by newlines, and the server will ignore any empty lines.
+
+You must have access to the host machine that you are deploying the server on to perform the
+initial registration of the admin user. You can get the public key of your `dsfxctl` client by running
+the `dsfxctl identity` command. You should then copy the base64 encoded public key and paste it into the
+`admins` file in the configuration directory.
+
+## User Management
+
+**todo**