forked from clan/clan-core
docs: self host documentation with mkDocs
This commit is contained in:
parent
f61a78a1cf
commit
1e08a454fb
6
docs/.envrc
Normal file
6
docs/.envrc
Normal file
@ -0,0 +1,6 @@
|
||||
source_up
|
||||
|
||||
watch_file flake-module.nix shell.nix default.nix
|
||||
|
||||
# Because we depend on nixpkgs sources, uploading to builders takes a long time
|
||||
use flake .#docs --builders ''
|
2
docs/.gitignore
vendored
Normal file
2
docs/.gitignore
vendored
Normal file
@ -0,0 +1,2 @@
|
||||
# build oputputs
|
||||
site
|
@ -1,10 +0,0 @@
|
||||
+++
|
||||
title = "Admin Documentation"
|
||||
description = "Documentation for administrators. Create and manage one or multiple cLANs"
|
||||
date = 2025-05-01T19:00:00+00:00
|
||||
updated = 2021-05-01T19:00:00+00:00
|
||||
template = "docs/section.html"
|
||||
weight = 15
|
||||
sort_by = "title"
|
||||
draft = false
|
||||
+++
|
26
docs/default.nix
Normal file
26
docs/default.nix
Normal file
@ -0,0 +1,26 @@
|
||||
{ pkgs, ... }:
|
||||
pkgs.stdenv.mkDerivation {
|
||||
name = "clan-documentation";
|
||||
|
||||
src = ./.;
|
||||
|
||||
nativeBuildInputs =
|
||||
[ pkgs.python3 ]
|
||||
++ (with pkgs.python3Packages; [
|
||||
mkdocs
|
||||
mkdocs-material
|
||||
mkdocs-drawio-exporter
|
||||
mkdocs-swagger-ui-tag
|
||||
plantuml-markdown
|
||||
]);
|
||||
|
||||
buildPhase = ''
|
||||
mkdocs build --strict
|
||||
|
||||
ls -la .
|
||||
'';
|
||||
|
||||
installPhase = ''
|
||||
cp -a site/ $out/
|
||||
'';
|
||||
}
|
@ -1,4 +1,4 @@
|
||||
# 03 Clan Hardware Installation
|
||||
# Hardware Installation
|
||||
|
||||
For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
|
||||
|
@ -1,4 +1,4 @@
|
||||
# 07 Backups
|
||||
# Backups
|
||||
|
||||
## Introduction to Backups
|
||||
|
@ -1,4 +1,4 @@
|
||||
# 08 Clan with `flake-parts`
|
||||
# Clan with `flake-parts`
|
||||
|
||||
Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows modular compositions.
|
||||
|
||||
@ -82,7 +82,7 @@ refer to the Clan module documentation located [here](https://git.clan.lol/clan/
|
||||
|
||||
### Next Steps
|
||||
|
||||
With your flake created, explore how to add new machines by reviewing the documentation provided [here](./02-machines.md).
|
||||
With your flake created, explore how to add new machines by reviewing the documentation provided [here](machines.md).
|
||||
|
||||
---
|
||||
|
@ -1,4 +1,4 @@
|
||||
# 01 Getting Started
|
||||
# Getting Started
|
||||
|
||||
Welcome to your simple guide on starting a new Clan project!
|
||||
|
||||
@ -7,7 +7,7 @@ Welcome to your simple guide on starting a new Clan project!
|
||||
We've put together a straightforward guide to help you out:
|
||||
|
||||
- [**Starting with a New Clan Project**](#starting-with-a-new-clan-project): Create a new Clan from scratch.
|
||||
- [**Integrating Clan using Flake-Parts**](./08-flake-parts.md)
|
||||
- [**Integrating Clan using Flake-Parts**](flake-parts.md)
|
||||
|
||||
---
|
||||
|
||||
@ -80,7 +80,7 @@ Open the `flake.nix` file and set a unique `clanName` if you want you can also s
|
||||
|
||||
**Right now clan assumes that you already have NixOS running on the target machine.**
|
||||
|
||||
If that is not the case you can use our [installer image](./05-install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
|
||||
If that is not the case you can use our [installer image](installer.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
|
||||
|
||||
On the remote execute:
|
||||
1. Generate a hardware-config.nix
|
||||
@ -107,11 +107,11 @@ On the remote execute:
|
||||
```
|
||||
|
||||
### **Next Steps**
|
||||
Ready to expand? Explore how to install a new machine with the helpful documentation [here](./02-machines.md).
|
||||
Ready to expand? Explore how to install a new machine with the helpful documentation [here](machines.md).
|
||||
Ready to explore more?
|
||||
|
||||
- **Adding New Machines to your setup**. [Following our templates](./99-templates.md)
|
||||
- **Adding New Machines to your setup**. [Following our templates](../templates/index.md)
|
||||
|
||||
- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how](./02-machines.md).
|
||||
- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how](machines.md).
|
||||
|
||||
---
|
@ -1,4 +1,4 @@
|
||||
# 03 Clan Installer
|
||||
# Installer
|
||||
|
||||
We offer a dedicated installer to assist remote installations.
|
||||
|
||||
@ -84,7 +84,7 @@ See: Guide for Wifi Below
|
||||
|
||||
### Whats next?
|
||||
|
||||
- [Deploying Machines](./02-machines.md): Deploying a Machine configuration
|
||||
- [Deploying Machines](machines.md): Deploying a Machine configuration
|
||||
- [WiFi](#optional-connect-to-wifi): Guide for connecting to Wifi.
|
||||
|
||||
---
|
@ -1,4 +1,4 @@
|
||||
# 02 Machines with Clan
|
||||
# Deploy Machine
|
||||
|
||||
Integrating a new machine into your Clan environment is a very easy yet flexible process, allowing for a straight forward management of multiple NixOS configurations.
|
||||
|
||||
@ -12,7 +12,7 @@ This process involves preparing a suitable hardware and disk partitioning config
|
||||
|
||||
### Step 0. Prerequisites
|
||||
|
||||
Boot the target machine using our [Clan Installer](./03-Installer.md). Which is recommended for ensuring most efficient workflows.
|
||||
Boot the target machine using our [Clan Installer](installer.md). Which is recommended for ensuring most efficient workflows.
|
||||
|
||||
Alternatively you can use any linux machine if it is reachable via SSH and supports `kexec`.
|
||||
|
||||
@ -23,9 +23,9 @@ ssh root@<your_target_machine_ip>
|
||||
```
|
||||
|
||||
- [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
|
||||
- [x] **Machine configuration**: You want to deploy. [Check out our templates](./99-templates.md)
|
||||
- [x] Initialized secrets: See [secrets](./06-secrets.md) for how to initialize your secrets.
|
||||
- [x] (Optional) USB Flash Drive with the [Clan Installer](./03-Installer.md)
|
||||
- [x] **Machine configuration**: You want to deploy. [Check out our templates](../templates/index.md)
|
||||
- [x] Initialized secrets: See [secrets](secrets.md) for how to initialize your secrets.
|
||||
- [x] (Optional) USB Flash Drive with the [Clan Installer](installer.md)
|
||||
|
||||
### Step 1. Identify Target Disk-ID
|
||||
|
@ -1,4 +1,4 @@
|
||||
# 04 Overlay Networks in Clan
|
||||
# Overlay Networks
|
||||
|
||||
This guide provides detailed instructions for configuring
|
||||
[ZeroTier VPN](https://zerotier.com) within Clan. Follow the
|
@ -1,4 +1,4 @@
|
||||
# 06 Secrets with Clan
|
||||
# Secrets
|
||||
|
||||
Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
|
||||
|
@ -1,13 +1,17 @@
|
||||
# 99 Templates
|
||||
# Templates
|
||||
|
||||
We provide some starting templates you can easily use one of those via `nix flakes`.
|
||||
|
||||
They showcase best practices and guide you through setting up and using Clan's modules
|
||||
|
||||
To use the `new-clan` template run the following command:
|
||||
I.e. To use the `new-clan` template run the following command:
|
||||
|
||||
`nix flake init -t git+https://git.clan.lol/clan/clan-core#new-clan`.
|
||||
|
||||
## Available Templates
|
||||
|
||||
We offer the following templates:
|
||||
|
||||
To initialize a clan with one of those run `nix flake init -t git+https://git.clan.lol/clan/clan-core#TEMPLATE_NAME`
|
||||
|
||||
- **new-clan**: Perfect for beginners, this template shows you how to link two machines in a basic setup.
|
13
docs/flake-module.nix
Normal file
13
docs/flake-module.nix
Normal file
@ -0,0 +1,13 @@
|
||||
{ inputs, ... }:
|
||||
{
|
||||
perSystem =
|
||||
{ self', pkgs, ... }:
|
||||
{
|
||||
devShells.docs = pkgs.callPackage ./shell.nix { inherit (self'.packages) docs; };
|
||||
packages = {
|
||||
docs = pkgs.python3.pkgs.callPackage ./default.nix { inherit (inputs) nixpkgs; };
|
||||
};
|
||||
|
||||
checks = self'.packages.clan-cli.tests;
|
||||
};
|
||||
}
|
68
docs/mkdocs.yml
Normal file
68
docs/mkdocs.yml
Normal file
@ -0,0 +1,68 @@
|
||||
site_name: Design
|
||||
site_url: https://docs.clan.lol
|
||||
repo_url: https://git.clan.lol/clan/clan-core/
|
||||
repo_name: clan-core
|
||||
edit_uri: _edit/main/docs/docs/
|
||||
|
||||
validation:
|
||||
omitted_files: warn
|
||||
absolute_links: warn
|
||||
unrecognized_links: warn
|
||||
|
||||
markdown_extensions:
|
||||
- footnotes
|
||||
- meta
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.highlight:
|
||||
use_pygments: true
|
||||
- pymdownx.superfences
|
||||
- plantuml_markdown
|
||||
- toc:
|
||||
title: On this page
|
||||
|
||||
exclude_docs: |
|
||||
.*
|
||||
!templates/
|
||||
/drafts/
|
||||
|
||||
nav:
|
||||
- Getting started:
|
||||
- getting-started/index.md
|
||||
- Deploy Machine: getting-started/machines.md
|
||||
- Installer: getting-started/installer.md
|
||||
- Setup Networking: getting-started/networking.md
|
||||
- Provision Secrets & Passwords: getting-started/secrets.md
|
||||
- Backup & Restore: getting-started/backups.md
|
||||
- Flake-parts: getting-started/flake-parts.md
|
||||
- Templates: templates/index.md
|
||||
- Contributing: contributing.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
features:
|
||||
- navigation.instant
|
||||
- navigation.tabs
|
||||
icon:
|
||||
repo: fontawesome/brands/git
|
||||
|
||||
palette:
|
||||
# Palette toggle for light mode
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
toggle:
|
||||
icon: material/weather-night
|
||||
name: Switch to dark mode
|
||||
|
||||
# Palette toggle for dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
toggle:
|
||||
icon: material/weather-sunny
|
||||
name: Switch to light mode
|
||||
|
||||
# extra_css:
|
||||
# - stylesheets/extra.css
|
||||
|
||||
plugins:
|
||||
- search
|
1
docs/shell.nix
Normal file
1
docs/shell.nix
Normal file
@ -0,0 +1 @@
|
||||
{ docs, pkgs, ... }: pkgs.mkShell { inputsFrom = [ docs ]; }
|
Loading…
Reference in New Issue
Block a user