initial import

docs/index.md

@@ -0,0 +1,4 @@
+### This is the main heading to use for the docs
+--8<--
+README.md
+--8<--

docs/installation/index.md

@@ -0,0 +1 @@
+# Installation

docs/installation/post-installation.md

@@ -0,0 +1,37 @@
+# Post-installation
+
+## Backup secrets
+
+Save the following files to a safe location like a password manager (if you're using the sandbox, you can skip this step):
+
+- `~/.ssh/id_ed25519`
+- `~/.ssh/id_ed25519.pub`
+- `./metal/kubeconfig.yaml`
+- `~/.terraform.d/credentials.tfrc.json`
+- `./external/terraform.tfvars`
+
+## Admin credentials
+
+- ArgoCD:
+    - Username: `admin`
+    - Password: run `./scripts/argocd-admin-password`
+- Vault:
+    - Root token: run `./scripts/vault-root-token`
+- Grafana:
+    - Username: `admin`
+    - Password: `prom-operator` (TODO: use random password)
+- Gitea:
+    - Username: `gitea_admin`
+    - Password: get from Vault
+
+## Run the full test suite
+
+After the homelab has been stabilized, you can run the full test suite to ensure that everything is working properly:
+
+```sh
+make test
+```
+
+!!! info
+
+    The "full" test suit is still in its early stages, so any contribution is greatly appreciated.

docs/installation/production/docker.md

@@ -0,0 +1,149 @@
+# Docker
+**Docker** is a set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called _containers_. The service has both free and premium tiers. The software that hosts the containers is called **Docker Engine**.
+
+Project Homepage: [Home - Docker](https://www.docker.com/)
+Documentation: [Docker Documentation | Docker Documentation](https://docs.docker.com/)
+
+---
+## Installation
+
+One click installation script:
+```
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+```
+
+Run docker as non root user:
+```
+sudo groupadd docker
+sudo usermod -aG docker $USER
+```
+
+Install Docker Engine : [Docker Engine](https://docs.docker.com/engine/install/)
+
+---
+## Build Images
+
+
+---
+## Docker CLI
+
+**Run Containers**
+
+COMMAND | DESCRIPTION
+---|---
+`docker run IMAGE` | Start a new container
+`docker run --name CONTAINER IMAGE` | Start a new container and set a name
+`docker run -p HOSTPORT:CONTAINERPORT IMAGE` | Start a new container with mapped ports
+`docker run -P IMAGE` | Start a new container and map all ports
+
+**Container Management:**
+
+COMMAND | DESCRIPTION
+---|---
+`docker create IMAGE` | Create a new container
+`docker start CONTAINER` | Start a container
+`docker stop CONTAINER` | Graceful stop a container
+`docker kill CONTAINER` | Kill (SIGKILL) a container
+`docker restart CONTAINER` | Graceful stop and restart a container
+`docker pause CONTAINER` | Suspend a container
+`docker unpause CONTAINER` | Resume a container
+`docker rm CONTAINER` | Destroy a container
+
+**Container Bulk Management**
+
+COMMAND | DESCRIPTION
+---|---
+`docker stop $(docker ps -q)` | To stop all the running containers
+`docker stop $(docker ps -a -q)` | To stop all the stopped and running containers
+`docker kill $(docker ps -q)` | To kill all the running containers
+`docker kill $(docker ps -a -q)` | To kill all the stopped and running containers
+`docker restart $(docker ps  -q)` | To restart all  running containers
+`docker restart $(docker ps -a -q)` | To restart all the stopped and running containers
+`docker rm $(docker ps  -q)` | To destroy all running containers
+`docker rm $(docker ps -a -q)` | To destroy all the stopped and running containers
+`docker pause $(docker ps  -q)` | To pause all  running containers
+`docker pause $(docker ps -a -q)` | To pause all the stopped and running containers
+`docker start $(docker ps  -q)` | To start all  running containers
+`docker start $(docker ps -a -q)` | To start all the stopped and running containers
+`docker rm -vf $(docker ps -a -q)` | To delete all containers including its volumes use
+`docker rmi -f $(docker images -a -q)` | To delete all the images
+`docker system prune` | To delete all dangling and unused images, containers, cache and volumes
+`docker system prune -a` | To delete all used and unused images
+`docker system prune --volumes` | To delete all docker volumes
+
+**Inspect Containers:**
+
+COMMAND | DESCRIPTION
+---|---
+`docker ps` | List running containers
+`docker ps -a` | List all containers, including stopped
+`docker logs CONTAINER` | Show a container output
+`docker logs -f CONTAINER` | Follow a container output
+`docker top CONTAINER` | List the processes running in a container
+`docker diff` | Show the differences with the image (modified files)
+`docker inspect` | Show information of a container (json formatted)
+
+**Run Commands:**
+
+COMMAND | DESCRIPTION
+---|---
+`docker attach CONTAINER` | Attach to a container
+`docker cp CONTAINER:PATH HOSTPATH` | Copy files from the container
+`docker cp HOSTPATH CONTAINER:PATH` | Copy files into the container
+`docker export CONTAINER` | Export the content of the container (tar archive)
+`docker exec CONTAINER` | Run a command inside a container
+`docker exec -it CONTAINER /bin/bash` | Open an interactive shell inside a container (there is no bash in some images, use /bin/sh)
+`docker wait CONTAINER` | Wait until the container terminates and return the exit code
+
+**Images:**
+
+COMMAND | DESCRIPTION
+---|---
+`docker images` | List all local images
+`docker history IMAGE` | Show the image history
+`docker inspect IMAGE` | Show information (json formatted)
+`docker tag IMAGE TAG` | Tag an image
+`docker commit CONTAINER IMAGE` | Create an image (from a container)
+`docker import URL` | Create an image (from a tarball)
+`docker rmi IMAGE` | Delete images
+`docker pull REPO:[TAG]` | pull an image/repo from a registry
+`docker push REPO:[TAG]` | push and image/repo to a registry
+`docker search TEXT` | Search an image on the official registry
+`docker login` | Login to a registry
+`docker logout` | Logout from a registry
+`docker save REPO:[TAG]` | Export an image/repo as a tarball
+`docker load` | Load images from a tarball
+
+**Volumes:**
+
+COMMAND | DESCRIPTION
+---|---
+`docker volume ls` | List all vol1umes
+`docker volume create VOLUME` | Create a volume
+`docker volume inspect VOLUME` | Show information (json formatted)
+`docker volume rm VOLUME` | Destroy a volume
+`docker volume ls --filter="dangling=true"` | List all dangling volumes (not referenced by any container)
+`docker volume prune` | Delete all volumes (not referenced by any container)
+
+### Backup a container
+Backup docker data from inside container volumes and package it in a tarball archive.
+`docker run --rm --volumes-from CONTAINER -v $(pwd):/backup busybox tar cvfz /backup/backup.tar CONTAINERPATH`
+
+An automated backup can be done also by this [Ansible playbook](https://github.com/thedatabaseme/docker_backup).
+The output is also a (compressed) tar. The playbook can also manage the backup retention.
+So older backups will get deleted automatically.
+
+To also create and backup the container configuration itself, you can use `docker-replay`for that. If you lose
+the entire container, you can recreate it with the export from `docker-replay`.
+A more detailed tutorial on how to use docker-replay can be found [here](https://thedatabaseme.de/2022/03/18/shorty-generate-docker-run-commands-using-docker-replay/).
+
+### Restore container from backup
+Restore the volume with a tarball archive.
+`docker run --rm --volumes-from CONTAINER -v $(pwd):/backup busybox sh -c "cd CONTAINERPATH && tar xvf /backup/backup.tar --strip 1"`
+## Networks
+
+## Troubleshooting
+### Networking
+`docker run --name netshoot --rm -it nicolaka/netshoot /bin/bash`
+

docs/installation/production/proxmox.md

@@ -0,0 +1,91 @@
+# Proxmox Installation Guide
+
+## System Requirements
+
+The following table lists the minimum system requirements for installing Proxmox:
+
+| Item | Requirement |
+|------|-------------|
+| CPU  | 64-bit processor (Intel or AMD) with Intel VT/AMD-V support |
+| RAM  | 4 GB or more |
+| Disk | 32 GB or more free disk space |
+
+## Installation Steps
+
+### 1. Download Proxmox ISO
+
+The first step is to download the Proxmox ISO file from the [official website](https://www.proxmox.com/en/downloads). Choose the appropriate ISO file for your server's architecture.
+
+![Proxmox Download](https://i.imgur.com/Xs2kj1A.png)
+
+### 2. Create a Bootable USB Drive
+
+Once you have downloaded the Proxmox ISO file, you need to create a bootable USB drive. You can use a tool like [Rufus](https://rufus.ie/) to create the bootable USB drive. Here is a quick guide:
+
+1. Insert the USB drive into your computer and launch Rufus.
+
+2. Rufus should automatically detect the USB drive. If not, select it from the Device dropdown.
+
+3. Select the Proxmox ISO file you downloaded earlier by clicking the SELECT button next to Boot selection.
+
+4. Leave the other settings as default and click START to begin creating the bootable USB drive.
+
+![Proxmox Rufus](https://i.imgur.com/nLbh8G1.png)
+
+### 3. Boot from the USB Drive
+
+Insert the bootable USB drive into the server you want to install Proxmox on and turn it on. You may need to change the boot order in your BIOS to boot from the USB drive.
+
+![Proxmox Boot](https://i.imgur.com/6ffclR9.png)
+
+### 4. Proxmox Installation
+Once the server boots from the USB drive, you will see the Proxmox installation menu.
+
+1. At the first screen, select **Install Proxmox VE** and hit ENTER to begin the installation.
+
+    ![Proxmox Installer Welcome Screen](https://i.imgur.com/6ffclR9.png)
+2. Click **I agree** button to accept the license agreement and continue the Proxmox installation.
+
+    ![License Agreement](https://i.imgur.com/6ffclR9.png)
+
+3. Next, choose target hard drive to install Proxmox and click Next. The Proxmox installer will automatically partition the selected hard disk, install all required packages and finally make the system bootble from the hard disk.
+        !!! note
+            if you proceed all existing partitions and data will be lost.
+
+    ![Choose Target Drive](https://i.imgur.com/6ffclR9.png)
+
+ollow the on-screen prompts to complete the installation. You will be asked to enter the following information:
+
+- Language selection
+- Timezone selection
+- Disk partitioning
+- Network configuration
+- Root password
+
+![Proxmox Setup](https://i.imgur.com/ylpAtWR.png)
+
+### 5. Access the Proxmox Web Interface
+
+After the installation is complete, you can access the Proxmox web interface by opening a web browser and navigating to the IP address of your server on port 8006:
+
+
+
+
+See Also
+--------
+
+* link:/wiki/Prepare_Installation_Media[Prepare Installation Media]
+
+* link:/wiki/Install_Proxmox_VE_on_Debian_Buster[Install Proxmox VE on Debian Buster]
+
+* link:/wiki/System_Requirements[System Requirements]
+
+* link:/wiki/Package_Repositories[Package Repositories]
+
+* link:/wiki/Host_System_Administration[Host System Administration]
+
+* link:/wiki/Network_Configuration[Network Configuration]
+
+* link:/wiki/Installation:_Tips_and_Tricks[Installation: Tips and Tricks]
+
+endif::wiki[]

docs/installation/sandbox.md

@@ -0,0 +1,86 @@
+# Development sandbox
+
+The sandbox is intended for trying out the homelab without any hardware or testing changes before applying them to the production environment.
+
+## Prerequisites
+
+Host machine:
+
+- Recommended hardware specifications:
+    - CPU: 4 cores
+    - RAM: 16 GiB
+- OS: Linux (Windows and macOS are untested, please let me know if it works)
+- Available ports: `80` and `443`
+
+Install the following packages:
+
+- `docker`
+- `make`
+
+Clone the repository and checkout the development branch:
+
+```sh
+git clone https://github.com/khuedoan/homelab
+git checkout dev
+```
+
+## Build
+
+Open the tools container, which includes all the tools needed:
+
+=== "Docker"
+
+    ```sh
+    make tools
+    ```
+
+=== "Nix"
+
+    ```sh
+    nix-shell
+    ```
+
+Build a development cluster and bootstrap it:
+
+```
+make
+```
+
+!!! note
+
+    It will take about 15 to 30 minutes to build depending on your internet connection
+
+## Explore
+
+The homepage should be available at <https://home.127-0-0-1.nip.io> (ignore the security warning because we don't have valid certificates).
+
+See [admin credentials](../post-installation/#admin-credentials) for default passwords.
+
+If you want to make some changes, simply commit to the local `dev` branch and push it to Gitea in the sandbox:
+
+```sh
+git remote add sandbox https://git.127-0-0-1.nip.io/ops/homelab
+git config http.https://git.127-0-0-1.nip.io.sslVerify false
+
+git add foobar.txt
+git commit -m "feat: harness the power of the sun"
+git push sandbox # you can use the gitea_admin account
+```
+
+## Clean up
+
+Delete the cluster:
+
+```sh
+k3d cluster delete homelab-dev
+```
+
+## Caveats compare to production environment
+
+The development cluster doesn't have the following features:
+
+- There is no valid domain name, hence no SSL certificates (some services require valid SSL certificates)
+- Only accessible on the host machine
+- No backup
+
+Please keep in mind that the development cluster may be unstable and things may break (it's for development after all).

mkdocs.yml

@@ -0,0 +1,78 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+site_name: KH3Group IT Documentation
+copyright: Copyright © 2022 - 2024 Siisi Nketsiah
+
+repo_url: https://git.office.kh3group.com/support/kh3-docs
+
+docs_dir: docs 
+
+theme:
+  name: material
+  palette:
+    primary: black
+  features:
+    - navigation.indexes
+    - navigation.sections
+    - search.highlight
+    - search.share
+
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - attr_list
+  - admonition
+  - pymdownx.details
+  - pymdownx.snippets:
+      check_paths: true
+  - def_list
+  - pymdownx.tasklist:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+
+nav:
+  - Home: index.md
+  - Installation:
+    - installation/index.md
+    - installation/sandbox.md
+    - Production:
+      - installation/production/index.md
+      - installation/production/prerequisites.md
+      - installation/production/proxmox.md
+      - installation/production/docker.md
+      - installation/production/external-resources.md
+      - installation/production/configuration.md
+      - installation/production/deployment.md
+    - installation/post-installation.md
+  - Getting started:
+    - getting-started/index.md
+    - getting-started/user-onboarding.md
+  - Concepts:
+    - concepts/index.md
+    - concepts/testing.md
+  - How-to guides:
+    - how-to-guides/index.md
+    - how-to-guides/alternate-dns-setup.md
+    - how-to-guides/expose-services-to-the-internet.md
+    - how-to-guides/use-both-github-and-gitea.md
+    - how-to-guides/updating-documentation.md
+    - Troubleshooting:
+      - how-to-guides/troubleshooting/index.md
+      - how-to-guides/troubleshooting/gitea.md
+  - Reference:
+    - reference/index.md
+    - Architecture:
+      - reference/architecture/index.md
+      - reference/architecture/overview.md
+      - reference/architecture/networking.md
+    - reference/license.md
+    - reference/changelog.md
+    - reference/roadmap.md
+    - reference/contributing.md
+    - reference/faq.md

requirements.txt

@@ -0,0 +1 @@
+mkdocs>=1.4.2