overhaul docs

book.toml

@@ -1,5 +1,5 @@
 [book]
-title = "DogeBox - Dogecoin Blockchain in a Box"
+title = "Dogebox"
 description = "Dogebox is a Linux server distribution and custom server software built specifically to meet the needs of the Dogecoin community."
 authors = ["qlpqlp", "tjstebbing", "s1w"]
 language = "en"
@@ -8,7 +8,9 @@ src = "src"
 [output.html]
 mathjax-support = true
 git-repository-url = "https://github.com/dogeorg/dogebox/"
+git-repository-icon = "fa-github"
 edit-url-template = "https://github.com/dogeorg/dogebox-docs/edit/main/{path}"
+cname = "dogebox-docs.dogecoin.org"
 
 [output.html.playground]
 editable = true

src/SUMMARY.md

@@ -1,12 +1,52 @@
 # Summary
 
-# What is DogeBox?
-
-- [Introduction](./what.md)
-- [Installation](./install.md)
-  - [Virtual Machines](./vms.md)
-  - [Bare Metal](./hardware.md)
-  - [Building images from source](./source_images.md)
-  - [Inbound Ports: 22556 (core), 42069 (Dogenet)](./ports.md)
-- [Installing Pups](./pup_install.md)
-- [DRE Development Environment](./development_environment.md)
+# Getting Started
+
+- [Introduction](./getting_started/introduction.md)
+- [Screenshots]()
+
+# Installation
+
+- [Getting Dogebox](./installation/getting.md)
+- [Bare Metal](./installation/metal.md)
+- [Virtual Machines](./installation/vms.md)
+
+  - [Virtualbox](./installation/vms/virtualbox.md)
+  - [UTM](./installation/vms/utm.md)
+  - [Generic VM](./installation/vms/generic.md)
+
+- [NanoPC T6](./installation/t6.md)
+
+  - [Purchasing]()
+  - [(Optional) Hardware Setup]()
+
+- [Dogebox Initial Setup](./installation/setup.md)
+  - [Disk Installation](./installation/setup/disk.md)
+  - [Configuration](./installation/setup/configuration.md)
+
+# How To
+
+- [Recovery Mode]()
+- [Installing Pups](./howto/pups.md)
+- [Forwarding Required Ports](./howto/ports.md)
+- [Updating & Upgrading]()
+
+---
+
+# Dogebox Development
+
+- [Development Environment Setup](./development/dre.md)
+- [Building Dogebox](./development/building.md)
+- [Pup Development]()
+
+  - [Manifest]()
+  - [Nix File]()
+  - [Dependencies]()
+  - [Communication]()
+  - [Metrics]()
+
+- [Dogeboxd]()
+- [DPanel]()
+
+- [Dogenet]()
+  - [Handlers]()

src/source_images.md → src/development/building.md

@@ -1,16 +1,14 @@
 # Building Dogebox
 
-
 Building images for Dogebox requires the Dogebox repository
 
 [https://github.com/dogeorg/dogebox/](https://github.com/dogeorg/dogebox/)
 
 For help building images be sure to join [Developer Discord Server](https://discord.gg/VEUMWpThg9)
 
-
 ## SD and SD installer images for the NanoPC-T6
 
-Start by building a disk image containing the root filesystem.  Assuming you are in an environment containing nix-shell, from the root of this repository run
+Start by building a disk image containing the root filesystem. Assuming you are in an environment containing nix-shell, from the root of this repository run
 
 ```
 nix-shell
@@ -31,9 +29,10 @@ cd sd-fuse_rk3588
 mkdir nixos-arm64
 ```
 
-sd-fuse wants an android sparse image and we have a raw full-disk image.  The following mount command mounts the partition inside the full disk image and build-rootfs-img.sh builds an android sparse image from the mounted directory and puts the result in nixos-arm64/rootfs.img
+sd-fuse wants an android sparse image and we have a raw full-disk image. The following mount command mounts the partition inside the full disk image and build-rootfs-img.sh builds an android sparse image from the mounted directory and puts the result in nixos-arm64/rootfs.img
 
 If /mnt is in use, use another location for the temporary mount.
+
 ```
 mount -o loop,offset=$((2048 * 512)) <location of the image created in the first step> /mnt
 ./build-rootfs-img.sh /mnt nixos-arm64
@@ -42,6 +41,7 @@ umount /mnt
 
 You can use prebuilt artifacts from this point, but if you intend to build the u-boot bootoarder from source, clone it's repository.
 If aarch64 cross compiling is not set up, the build script shoul fail with instructions containing what it's looking for.
+
 ```
 cd out
 git clone https://github.com/dogeorg/uboot-rockchip.git uboot-rk3588
@@ -52,6 +52,7 @@ cd ../../
 ```
 
 Add any remaining artifacts to the 'nixos-arm64' directory
+
 ```
 idbloader.img
 uboot.img
@@ -63,6 +64,7 @@ boot.img
 ```
 
 Run the image builing script
+
 ```
 ./mk-sd-image.sh nixos-arm64
 ```
@@ -117,4 +119,3 @@ Generates a VMDK file that can be used by VMware or VirtualBox VMs directly
 If you'd prefer a VDI, you can convert with `VBoxManage clonehd --format VDI <from>.vmdk <to>.vdi`
 
 Generating a VDI out of the box with `-f virtualbox` doesn't appear to be working currently with the default config.
-

src/development/dogeboxd.md

@@ -0,0 +1 @@
+# Dogeboxd

src/development/dogenet.md

@@ -0,0 +1 @@
+# Dogenet

src/development/dogenet/handlers.md

@@ -0,0 +1 @@
+# Handlers

src/development/dpanel.md

@@ -0,0 +1 @@
+# DPanel

src/development/dre.md

@@ -0,0 +1,133 @@
+# DRE Development Environment
+
+The Dogebox exclusively runs on NixOS as its linux-base.
+
+### Install NixOS in a VM
+
+There are multiple ways of accomplishing this. The easiest way by far is to use [Orbstack](https://orbstack.dev/) which supports NixOS VMs natively, and provides useful filesystem and host-network sharing.
+
+The rest of this guide will assume you are using Orbstack, or a VM solution that lets you bind to your hosts network interfaces.
+
+### Clone required repositories
+
+There are 3 repositories that provide the foundational building blocks for Dogebox. Please `git clone` all of these.
+
+- [Dogeboxd](https://github.com/dogeorg/dogeboxd) - `https://github.com/dogeorg/dogeboxd.git`
+- [DPanel](https://github.com/dogeorg/dpanel) - `https://github.com/dogeorg/dpanel.git`
+- [DKM](https://github.com/dogeorg/dkm) - `https://github.com/dogeorg/dkm.git`
+
+Please note: `dogeboxd` & `dpanel` must be cloned into the same parent directory. You can clone `DKM` anywhere.
+
+### Configure your Nix environment
+
+As we're running a development environment, some things must be configured manually.
+
+#### Import `dogebox.nix`
+
+Edit `/etc/nixos/configuration.nix`. Towards the top of the file there should be an `imports` section.
+
+Please modify it to conditionally include the `dogebox.nix` file that will live in `$HOME/data/nix/dogebox.nix`
+
+For example, if your existing imports block looks like:
+
+```nix
+  imports =
+    [
+      "${modulesPath}/virtualisation/lxc-container.nix"
+      ./lxd.nix
+    ];
+```
+
+Please change it to:
+
+```nix
+  imports =
+    [
+      "${modulesPath}/virtualisation/lxc-container.nix"
+      ./lxd.nix
+    ] ++ lib.optionals (builtins.pathExists "/home/$USER/data/nix/dogebox.nix") [
+      /home/$USER/data/nix/dogebox.nix
+    ];
+```
+
+Where `$USER` is the user you have inside your NixOS VM.
+
+#### Add required packages
+
+Edit `/etc/nixos/configuration.nix`. Inside the main `{ ... }` block, please add:
+
+```nix
+environment.systemPackages = [ pkgs.git pkgs.vim ];
+```
+
+nb. Vim is not required, but lots of people get annoying that it is not available :)
+
+#### Add required security wrappers
+
+Edit `/etc/nixos/configuration.nix`. Inside the main `{ ... }` block, please add:
+
+```nix
+security.wrappers.dbx = {
+  source = "/home/$USER/dogeboxd/build/dbx";
+  owner = "$USER";
+  group = "users";
+};
+
+security.wrappers.dogeboxd = {
+  source = "/home/$USER/dogeboxd/build/dogeboxd";
+  capabilities = "cap_net_bind_service=+ep";
+  owner = "$USER";
+  group = "users";
+};
+
+security.wrappers._dbxroot = {
+  source = "/home/$USER/dogeboxd/build/_dbxroot";
+  owner = "root";
+  group = "root";
+  setuid = true;
+};
+```
+
+**Please note:** Please fix these paths, they assume you have cloned `dogeboxd` into the users home directory. If you cloned them elsewhere, update the paths.
+**Please note:** There are multiple instances of `$USER` that need replacing, please update all of them.
+
+#### Rebuild
+
+Once you've added the above, you can rebuild your VM to ensure it's in a proper state to execute everything.
+
+Please run: `sudo nixos-rebuild switch`. Assuming this succeeds, you're ready to rock and roll.
+
+### Starting Services
+
+You need to be running `dogeboxd` and `dkm` at the same time to have things working. `dpanel` is served via `dogeboxd` automatically, assuming they've been cloned into the same parent directory.
+
+Both services contain a `shell.nix` which provides all the necessary dependencies for executing the service.
+
+Both services also contain a `Makefile` that provides a `dev` command that run things in a "default" development mode.
+
+##### Starting `dogeboxd`
+
+```bash
+cd dogeboxd
+nix-shell
+make dev
+```
+
+##### Starting `dkm`
+
+```bash
+cd dkm
+nix-shell
+make dev
+```
+
+`dogeboxd` should now be listening on [http://127.0.0.1:3000](http://127.0.0.1:3000) and should be ready in setup mode.
+
+After initial setup has completed, you will need to re-run `make dev` for `dogeboxd` to launch it again in normal-mode. Please see below for more details.
+
+### Things to note
+
+- In development mode, any time the service would trigger a `shutdown` or `restart`, the dogeboxd process will `exit` instead.
+- In development mode your dogeboxd/dpanel sessions will persist across service restarts. This will not happen in non-development mode.
+- You can run `make recovery` to force dogeboxd into recovery mode.
+- All data for both `dogeboxd` and `DKM` is written to `~/data`. Deleting this directory will reset your state.

src/development/pups.md

@@ -0,0 +1 @@
+# Pup Development

src/development/pups/communication.md

@@ -0,0 +1 @@
+# Communication

src/development/pups/dependencies.md

@@ -0,0 +1 @@
+# Dependencies

src/development/pups/manifest.md

@@ -0,0 +1 @@
+# Manifest

src/development/pups/metrics.md

@@ -0,0 +1 @@
+# Metrics

src/development/pups/nix.md

@@ -0,0 +1 @@
+# Nix File