From 7522a721df84136042cfe8a291f2b1aeb8242aa8 Mon Sep 17 00:00:00 2001
From: Olivier <olivier@librepush.net>
Date: Fri, 1 Jan 2021 14:27:43 +0000
Subject: [PATCH] Introduce documentation.

---
 docs/.gitignore              |  1 +
 docs/book.toml               | 15 +++++++++
 docs/src/SUMMARY.md          | 21 ++++++++++++
 docs/src/architecture.md     | 21 ++++++++++++
 docs/src/index.md            | 11 ++++++
 docs/src/recipes/declare.md  | 65 ++++++++++++++++++++++++++++++++++++
 docs/src/recipes/os/users.md | 37 ++++++++++++++++++++
 docs/src/starting/sous.md    | 54 ++++++++++++++++++++++++++++++
 8 files changed, 225 insertions(+)
 create mode 100644 docs/.gitignore
 create mode 100644 docs/book.toml
 create mode 100644 docs/src/SUMMARY.md
 create mode 100644 docs/src/architecture.md
 create mode 100644 docs/src/index.md
 create mode 100644 docs/src/recipes/declare.md
 create mode 100644 docs/src/recipes/os/users.md
 create mode 100644 docs/src/starting/sous.md

diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..7585238
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/docs/book.toml b/docs/book.toml
new file mode 100644
index 0000000..7343727
--- /dev/null
+++ b/docs/book.toml
@@ -0,0 +1,15 @@
+[book]
+authors = ["Olivier"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Scone Documentation"
+description = "Documentation for Scone (Server CONfiguration Engine)"
+
+[output.html]
+default-theme = "rust"
+git-repository-url = "https://bics.ga/reivilibre/scone"
+git-repository-icon = "fa-git-alt"
+fold = { enable = true, level = 1 }
+
+# TODO scoml and toml highlighting
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
new file mode 100644
index 0000000..1860db0
--- /dev/null
+++ b/docs/src/SUMMARY.md
@@ -0,0 +1,21 @@
+# Summary
+
+- [Scone](./index.md)
+- [Architecture](./architecture.md)
+- [Getting Started](./starting/index.md)
+  - [Installing scone](./starting/install.md)
+  - [Creating your first head chef and restaurant](./starting/head.md)
+  - [Installing scone to a server and creating a sous chef](./starting/sous.md)
+  - [Cooking your first menu](./starting/first_cook.md)
+  - [Using the Fridge and Freezer](./starting/fridge_freezer.md)
+- [Recipes](./recipes/index.md)
+  - [Declare](./recipes/declare.md)
+  - [Operating System Recipes](./recipes/os/index.md)
+    - [Users](./recipes/os/users.md)
+  - [Filesystem Recipes](./recipes/filesystem/index.md)
+  - [Database Recipes](./recipes/database/index.md)
+    - [Postgres](./recipes/database/postgres.md)
+  - [Docker](./recipes/docker.md)
+- [Resources](./resources/index.md)
+  - [Filesystem Resources](./resources/filesystem.md)
+- [Utensils]()
diff --git a/docs/src/architecture.md b/docs/src/architecture.md
new file mode 100644
index 0000000..b2c386b
--- /dev/null
+++ b/docs/src/architecture.md
@@ -0,0 +1,21 @@
+# Architecture
+
+A controlling host, called the `head` chef, is responsible for sending commands to other hosts over SSH.
+The hosts being controlled are called `sous` chefs.
+
+The head chef owns all the instructions and data needed to set up the sous chefs as desired.
+
+Recipes are arranged in a directed acyclic graph (DAG); recipes can depend on each other so that they are ran sequentially (otherwise, recipes will be run in parallel, because time is precious).
+
+'Resources' are also present in the DAG and are allowed to have edges between themselves and recipes. The conceptual idea is that some recipes **provide** resources (such as files) and others **need** them.
+
+## Definitions
+
+* **restaurant**: Collection of head configuration, sous configuration, menus and a fridge. It is the whole repository of configuration.
+* **head**: Host that instructs other hosts
+* **sous**: Host that is instructed by other hosts
+* **recipe**: A job that produces something, such as a file, or a certain configuration.
+* **menu**: A collection of recipes
+* **fridge**: Store of 'ingredients' — data (files, templates and variables) needed to cook recipes.
+  * **freezer**: Like a fridge, but encrypted on the host
+* **supermarket**: Source of ingredients which can't be kept persistently in the fridge for some reason.
diff --git a/docs/src/index.md b/docs/src/index.md
new file mode 100644
index 0000000..4ba1c74
--- /dev/null
+++ b/docs/src/index.md
@@ -0,0 +1,11 @@
+# Scone
+
+Scone is a tool to help you set up your server(s) reliably and automatically.
+
+You can write the configuration needed to bring your services up and use these
+to configure your servers again and again.
+
+This configuration is declarative and can be tracked in version control.
+
+
+Scone is still an alpha project.
diff --git a/docs/src/recipes/declare.md b/docs/src/recipes/declare.md
new file mode 100644
index 0000000..87403df
--- /dev/null
+++ b/docs/src/recipes/declare.md
@@ -0,0 +1,65 @@
+# Declare
+
+Sometimes we need to tell Scone that a resource already exists on the sous, and that scone doesn't need it to be provided by the menu.
+
+The solution to this is to have no-operation recipes that provide these resources.
+
+| Recipe | Needs | Provides |
+| -----: | ----- | -------- |
+| [`declare-os-user`](#declare-os-user) | | `os-user` |
+| [`declare-dir`](#declare-dir) | | `directory` |
+| [`declare-file`](#declare-file) | | `file` |
+
+
+## `declare-os-user`
+
+**Preconditions**: the OS user *must already exist on the sous*.
+
+**Provides**: `os-user(?)` where `?` is the argument `name`.
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| name | any username string | *required* | Username of the OS (e.g. Linux) user that already exists. |
+
+### Example
+
+```scoml
+[[declare-os-user]]
+name = root
+```
+
+
+## `declare-dir`
+
+**Preconditions**: the specified directory *must already exist on the sous*.
+
+**Provides**: `directory(?)` where `?` is the argument `path`.
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| path | any path string | *required* | Path of the directory that already exists. |
+
+### Example
+
+```scoml
+[[declare-dir]]
+path = /etc/systemd/system
+```
+
+
+## `declare-file`
+
+**Preconditions**: the specified file *must already exist on the sous*.
+
+**Provides**: `file(?)` where `?` is the argument `path`.
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| path | any path string | *required* | Path of the file that already exists. |
+
+### Example
+
+```scoml
+[[declare-file]]
+path = /etc/passwd
+```
diff --git a/docs/src/recipes/os/users.md b/docs/src/recipes/os/users.md
new file mode 100644
index 0000000..eaacc85
--- /dev/null
+++ b/docs/src/recipes/os/users.md
@@ -0,0 +1,37 @@
+# Users
+
+Users are a fundamental concept in modern operating systems.
+
+It is useful to be able to create them, both for operators and for services.
+
+| Recipe | Needs | Provides |
+| -----: | ----- | -------- |
+| [`os-user`](#os-user) | | `os-user` |
+
+
+## `os-user`
+
+Creates a user.
+
+**Note:** probably must be run as the `root` user.
+
+**Provides**: `os-user(?)` where `?` is the argument `name`.
+
+| Argument | Accepted Values | Default | Description |
+| -------: | --------------- | ------- | ----------- |
+| name | any username string | *required* | Username of the OS (e.g. Linux) user that already exists. |
+| make_group | true, false | true | True if the user should have its own group with the same name. |
+| make_home | true, false | true | True if the user's home directory should be created. |
+| home | any path string | *optional* | Directory for the user's home. If not specified, the operating system will choose it. |
+| password | any string | *optional* | Password for the user. If not specified, no password will be created. |
+
+### Example
+
+Idiomatic example, showing running the recipe as a root user and declaring the provision of the user's home directory.
+
+```scoml
+[[os-user]]
+@provides directory(/home/hedgedoc)
+@user = root
+name = hedgedoc
+```
diff --git a/docs/src/starting/sous.md b/docs/src/starting/sous.md
new file mode 100644
index 0000000..b87bdfe
--- /dev/null
+++ b/docs/src/starting/sous.md
@@ -0,0 +1,54 @@
+# Installing scone to a server and creating a sous chef
+
+These instructions are provided for Debian-like servers.
+
+## Create a user for your sous
+
+Log in as root on the server you want to control with scone.
+Create a user for scone.
+```
+# adduser --disabled-password scone
+```
+
+Make your scone user have passwordless sudo capability.
+```
+# echo 'scone ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/scone
+# chmod 0440 /etc/sudoers.d/scone
+# visudo -c # check sudoers file
+```
+
+## Install scone on your sous
+
+You'll need the SSH public key for your controlling computer here;
+try looking in `/home/$USER/.ssh/id_ed25519.pub` or `/home/$USER/.ssh/id_rsa.pub`.
+
+Alternatively, I suggest generating a new SSH key in your password manager, such as
+KeePassXC, and adding it to your SSH agent as-and-when you need to use Scone.
+
+```
+# su scone
+$ cd
+$ mkdir .ssh
+$ echo 'ssh-ed25519 AA...bJ user@headmachine' >> .ssh/authorized_keys # use your own SSH public key here
+$ chmod -R go-rw .ssh
+```
+
+Now activate your Scone virtual environment on your host and run, from within
+the `scone` repository directory on your host:
+```
+./contrib/install_scone.sh scone@machine.example.org
+```
+
+## Add to your head configuration
+
+Finally, add a section to your `scone.head.toml` file to describe the new installation
+you have made.
+
+```toml
+[sous.machine]
+host = "machine.example.org"
+user = "scone"
+souscmd = "/home/scone/.scone/venv/bin/python -m scone.sous ~/.scone"
+```
+
+TODO: `scone.sous.toml`, `[groups]`, ...