first iteration of more formal docs

Author: sryps

docs/operational-docs/.gitignore

@@ -0,0 +1 @@
+.env

docs/operational-docs/README.md

@@ -0,0 +1,62 @@
+# Emerald - Documentation
+
+To install to view locally:
+
+```bash
+python3 -m venv ~/mkdocs-env
+source ~/mkdocs-env/bin/activate
+pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocs-github-admonitions-plugin
+mkdocs --version # To verify the installation
+```
+
+To view the documentation locally:
+
+```bash
+mkdocs serve
+```
+
+When you are done, deactivate the virtual environment:
+
+```bash
+deactivate
+```
+
+### How to Add Documentation
+
+`mkdocs awesome-pages` plugin is used to auto generate the navigation for nested directories in `docs/`.
+
+To add a new page, create a new markdown file in the `docs/{topic}/` directory. The file should have a `.md` extension.
+
+Each directory 1 level into `docs/` should have an `index.md` file. This file should contain the title `Overview` and a brief description of the contents of the directory.
+
+All nested directories only need to contain the documentation files for the topics they cover.
+Example `docs/infra/ovh/provision-server.md` will be automatically added to the navigation.
+
+### How to Style Documentation
+
+`mkdocs-github-admonitions-plugin` is used to support GitHub-style admonitions in markdown files. These are rendered consistently in both GitHub and in our MkDocs documentation.
+
+For detailed information on formatting, including:
+- Using admonitions (notes, warnings, tips, etc.)
+- Code block formatting
+- Links and references
+- Other styling guidelines
+
+Please refer to the [MkDocs Styling Guide](docs/mkdocs-styling-guide.md) for comprehensive styling guidelines and examples.
+
+## Using Docker Compose
+
+Setup your environment to have the same user inside the container.
+
+```bash
+echo "UID=$(id -u)" > .env
+echo "GID=$(id -g)" >> .env
+echo "USERNAME=$(id -un)" >> .env
+```
+
+Start the container, which also builds the image.
+
+```bash
+docker compose up -d
+```
+

docs/operational-docs/compose.yml

@@ -0,0 +1,14 @@
+---
+services:
+  mkdocs:
+    build:
+      context: .
+      args:
+        UID: ${UID}
+        GID: ${GID}
+        USERNAME: ${USERNAME}
+    volumes:
+      - ./:/docs
+    ports:
+      - "8000:8000"
+

docs/operational-docs/dockerfile

@@ -0,0 +1,32 @@
+# -- --
+FROM python:3.9-slim
+
+# -- install required packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    neovim \
+    curl \
+    git \
+    ca-certificates \
+    less \
+    && pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocs-github-admonitions-plugin \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Build args for user info
+ARG UID=1000
+ARG GID=1000
+ARG USERNAME=docsuser
+
+# -- create group, user, and set permissions
+RUN addgroup --gid ${GID} ${USERNAME} && \
+    adduser --disabled-password --uid ${UID} --gid ${GID} ${USERNAME}
+
+COPY docs /docs/docs
+COPY mkdocs.yaml /docs/mkdocs.yaml
+# -- set working dir
+WORKDIR /docs
+
+# -- run as user
+USER ${USERNAME}
+
+EXPOSE 8000
+CMD ["mkdocs", "serve", "-a", "0.0.0.0:8000"]

docs/operational-docs/docs/create-new-network/emerald-config.toml

@@ -0,0 +1,16 @@
+moniker = "test-0"
+execution_authrpc_address = "http://<RETH_IP>:8545"
+engine_authrpc_address = "http://<RETH_IP>:8551"
+jwt_token_path = "/home/emerald/jwt"
+el_node_type = "archive"
+sync_timeout_ms = 1000000
+sync_initial_delay_ms = 100
+
+max_retain_blocks = 0
+prune_at_block_interval = 5
+
+[retry_config]
+initial_delay = "100ms"
+max_delay = "5s"
+max_elapsed_time = "30s"
+multiplier = 2.0

docs/operational-docs/docs/create-new-network/emerald.systemd.service.example

@@ -0,0 +1,33 @@
+[Unit]
+Description=Emerald Consensus Engine (Malachite BFT)
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=emerald
+Group=emerald
+
+# Working directory
+WorkingDirectory=/home/emerald
+
+# Environment
+Environment="RUST_LOG=info"
+Environment="RUST_BACKTRACE=1"
+
+# Start Emerald node
+ExecStart=/usr/local/bin/emerald start \
+  --home /var/lib/emerald/node0
+ExecStart=/usr/local/bin/emerald start \
+  --home /home/emerald/.emerald \
+  --config /home/emerald/.emerald/config/emerald.toml \
+  --log-level info
+
+# Restart configuration
+Restart=on-failure
+RestartSec=10s
+TimeoutStopSec=30s
+KillMode=process
+KillSignal=SIGTERM
+
+[Install]
+WantedBy=multi-user.target