From 709b4d8e1e8d184b3ce1d8a7e9f97f9d54c06657 Mon Sep 17 00:00:00 2001
From: Dustin Stiles <duwstiles@pm.me>
Date: Sun, 23 Mar 2025 10:56:35 -0400
Subject: [PATCH] docs(administration): initial scaffolding

---
 docs/administration.md | 76 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/docs/administration.md b/docs/administration.md
index 50642c7..d52b9d0 100644
--- a/docs/administration.md
+++ b/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**