Add version 1.x docs

.github/workflows/build-docs.yml

@@ -6,7 +6,7 @@ on:
 permissions:
   contents: write
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -21,5 +21,5 @@ jobs:
           restore-keys: |
             mkdocs-material-
       - run: sudo apt install pngquant
-      - run: pip install mkdocs-material mkdocs-awesome-pages-plugin pillow cairosvg
+      - run: pip install mkdocs-material mkdocs-awesome-pages-plugin pillow cairosvg mike mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2
       - run: mkdocs build

.gitignore

@@ -1,2 +1,3 @@
 .cache
-site/
+site/
+.env

.markdownlint.yaml

@@ -1,7 +1,7 @@
 MD013:
   line_length: 120
-MD033:
-  allowed_elements:
-    - "figure"
-    - "figcaption"
+MD033: false
 MD046: false # Code block style errors interfere with admonitions
+MD007:
+  indent: 4
+MD030: false

.vscode/settings.json

@@ -5,5 +5,8 @@
   },
   "editor.wordWrapColumn": 120,
   "editor.wordWrap": "wordWrapColumn",
-  "editor.rulers": [120]
+  "editor.rulers": [120],
+  "editor.tabSize": 4,
+  "editor.indentSize": "tabSize",
+  "editor.detectIndentation": false
 }

README.md

@@ -1,6 +1,6 @@
 # CBLE Documentation
 
-[![Deploy Docs](https://github.com/cble-platform/docs/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/cble-platform/docs/actions/workflows/deploy-docs.yml)
+[![Build Docs](https://github.com/cble-platform/docs/actions/workflows/build-docs.yml/badge.svg)](https://github.com/cble-platform/docs/actions/workflows/build-docs.yml)
 
 This documentation is built with `mkdocs` and uses [Poetry](https://python-poetry.org/) for dependency management.
 
@@ -15,7 +15,25 @@ To build the site locally, just run `mkdocs build` and the static site will be g
 
 ## Deployment
 
-The site is automatically built and deployed via GitHub actions.
+This site is using versioned documentation with [mike](https://github.com/jimporter/mike).
+
+> ⚠️ To deploy a new version, **merge all changes into `main` first**
+
+```shell
+git switch main
+
+mike deploy -t "x.x (latest)" x.x latest
+
+mike serve
+
+# Check to ensure generated site is good to go
+
+git switch gh-pages
+
+git push
+
+git switch main
+```
 
 ## Development
 

cf_build.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Build script for deploying to Cloudflare Pages (https://community.cloudflare.com/t/different-build-commands-for-build-previews/266084)
+
+if [ "$CF_PAGES_BRANCH" == "gh-pages" ]; then
+  # Just copy the output into the site/ dir on gh-pages (already built by mike)
+  mkdir site/
+  ls | grep -v "site" | xargs -n1 mv -t site
+else
+  # Else run mkdocs build to compile in Poetry venv
+  poetry run mkdocs build
+fi

docs/.pages

@@ -1,4 +1,4 @@
 nav:
-  - Overview: index.md
+  - index.md
   - getting-started
   - references

docs/getting-started/.pages

@@ -1,5 +1,8 @@
 nav:
-  - Quick Start: quick-start.md
-  - providers
-  - blueprints
+  - installation.md
+  - quick-intro.md
+  - Behind the Scenes:
+      - providers
+      - blueprints
+      - projects
   - ...

docs/getting-started/blueprints/concepts.md

@@ -4,8 +4,8 @@ There are a few key concepts to understand when working with CBLE blueprints:
 
 ## Resources
 
-A resource represents _something_ which would be deployed in the cloud. This might be a server, a database, a load balancer,
-a router, anything you can deploy in the cloud (which CBLE supports; see [Providers](#)).
+A resource represents something which _could be deployed_ in the cloud. This might be a server, a database, a load balancer,
+a router, anything you can deploy in the cloud (with provider support).
 
 Let's use this resource as an example:
 
@@ -35,4 +35,21 @@ There is a lot to unpack here, but let's unpack line-by-line:
    will not be deployed until all `depends_on` resources are successful. This resource will be destroyed before any `depends_on`
    resources are destroyed
 
-For more information on the resource configs, please refer to the [provider documentation](#).
+For more information on resource configs for a provider, please refer to the [provider's documentation](../providers/overview.md#supported-providers).
+
+## Data Source
+
+A data source represents something which _is already deployed_ in the cloud. This might be a server, a database, a load balancer,
+a router, anything you can deploy in the cloud (with provider support).
+
+Let's use this data source as an example:
+
+```yaml title="Example data source"
+main_nat:
+  data: openstack.v1.network
+  config:
+    name: MAIN-NAT
+```
+
+While this looks similar to a resource, instead of using the `config` block to deploy and configure a resource, the provider
+will look up an existing resource in the attached cloud environment which matches this config.

docs/getting-started/blueprints/overview.md

@@ -20,22 +20,26 @@ host1:
       network1:
         dhcp: false
         ip: 10.10.0.1
-  depends_on: # (4)!
-    - router1
+    depends_on: # (4)!
+      - router1
+
+main_nat:
+  data: openstack.v1.network # (5)!
+  config:
+    name: MAIN-NAT
 
 host2:
   resource: openstack.v1.host
   config:
-    hostname: host2
+    hostname: "{{ .Host2Hostname }}"
     image: UbuntuJammy2204-Desktop
     flavor: medium
     disk_size: 25
     networks:
-      network1:
+      main_nat:
         dhcp: true
-  depends_on:
-    - host1
-    - router1
+    depends_on:
+      - host1
 
 network1:
   resource: openstack.v1.network
@@ -49,7 +53,7 @@ network1:
 router1:
   resource: openstack.v1.router
   config:
-    external_network: MAIN-NAT
+    external_network: main_nat
     networks:
       network1:
         dhcp: false
@@ -62,3 +66,5 @@ router1:
 4. `depends_on` is similar to **Docker Compose v3**. This allows us to wait on other objects to deploy _before_ we
    deploy this object (and destroy this object _before_ we destroy the parents). Providers _should_ provide inherent
    dependencies based on resource types.
+5. This is called a **data type**. Data types are similar to resource types, but instead of deploying resources they
+   pull pre-existing resources and information from the provider without modification.

docs/getting-started/installation.md

@@ -0,0 +1,169 @@
+# Installation
+
+!!! info "Base OS Selection"
+
+    This deployment has only been tested on **Fedora 38/39** and **Ubuntu 22.04**
+
+## Automatic Installation (Recommended)
+
+Use the auto-installer to download CBLE and its prerequisites:
+
+```shell
+. <(curl -fsSL https://get.cble.io)
+```
+
+!!! warning "Shell Support"
+
+    The auto installer has only been tested with the **zsh** and **bash** shells
+
+Follow the automatic installer prompts to automatically configure CBLE:
+
+```shell
+Installing Docker...
+# Executing docker install script, commit: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# ... docker install output ...
+
+Cloning into 'cble'...
+# ... git output ...
+Would you like to perform auto-configuration of CBLE? [Y/n] Y
+Are you using SSL (requires DNS to be set up)? [Y/n] Y
+What is the domain (FQDN) you plan to use (e.g. cble.io): <your fqdn>
+Would you like to generate random passwords/keys? [Y/n] Y
+Default admin account username [cble]: cble
+Default admin account first name [CBLE]: CBLE
+Default admin account last name [Admin]: Admin
+
+CBLE has been installed and auto-configured!
+
+Once ready, start CBLE with:
+
+    cd cble
+    docker compose -f docker-compose.local.yml build
+    docker compose -f docker-compose.local.yml up -d
+
+Then log in with the following credentials:
+
+    Name: CBLE Admin
+    Username: cble
+    Password: <random password>
+```
+
+Now run CBLE with:
+
+```shell
+cd cble
+docker compose -f docker-compose.local.yml build
+docker compose -f docker-compose.local.yml up -d
+```
+
+## Manual Installation
+
+### Installation Methods
+
+#### Docker (Recommended)
+
+Install [Docker](https://docker.com) with:
+
+```shell
+curl -fsSL https://get.docker.com/ | sh
+```
+
+Clone the CBLE repository:
+
+```shell
+git clone https://github.com/cble-platform/cble
+```
+
+Move into the deploy directory and create local configuration files from the provided examples:
+
+```shell
+cd cble
+cp config.example.yaml config.local.yaml
+cp Caddyfile.example Caddyfile
+cp docker-compose.yml docker-compose.local.yml
+```
+
+To start CBLE, first build the container images and the run the containers:
+
+```shell
+docker compose -f docker-compose.local.yml build
+docker compose -f docker-compose.local.yml up -d
+```
+
+#### System-wide
+
+Coming soon.
+
+### Configuration
+
+For these next steps you'll need to know the Fully Qualified Domain Name (FQDN) of the deployment. This
+would look something like `https://docs.cble.io`.
+
+!!! tip "FQDN Configuration"
+
+    The FQDN *must* have DNS set up in order to perform automatic TLS certificate provisioning. Be sure
+    to set up your DNS `A/AAAA` records to point to the CBLE server.
+
+First, edit the `config.local.yaml` file (see
+[Config File Reference](../references/config-file.md) for more options):
+
+```yaml title="config.local.yaml"
+# ...
+server:
+  hostname: <your fqdn>
+  # ...
+  ssl: true # enable this to auto-provision a TLS certificate
+  # ...
+  origins:
+    - https://<your fqdn> # put your FQDN here
+# ...
+database:
+  # ...
+  password: <secure password> # set this to a secure password for the database
+# ...
+auth:
+  jwt_key: <random jwt key> # generate a random value here
+  # (easy method; requires node) node -e "console.log(require('crypto').randomBytes(64).toString('hex'));"
+  # ...
+initialization:
+  default_admin:
+    # ...
+    password: <secure password> # generate a secure password for the default admin user
+  # ...
+```
+
+Place your FQDN at the top of the `Caddyfile`:
+
+```text title="Caddyfile"
+<your fqdn> { # be sure to delete the "http://" at the beginning
+    # ...
+}
+```
+
+Update the configuration in the `docker-compose.local.yml`:
+
+```yaml title="docker-compose.local.yaml"
+services:
+  frontend:
+    build:
+      # ...
+      args:
+        - VITE_API_BASE_URL=https://<your fqdn> # put your FQDN here
+    # ...
+  backend:
+    # ...
+  db:
+    # ...
+    environment:
+      # ...
+      - POSTGRES_PASSWORD=<secure password> # secure password from the `database` section of `config.local.yaml`
+      # ...
+```
+
+## Login to CBLE
+
+You can now visit the CBLE dashboard at `https://<your fqdn>`. You should be greeted with the login page:
+
+![Login Page](./login-fs8.png){ loading=lazy }
+
+Log in with the username and password you created during configuration.

docs/getting-started/projects/.pages

@@ -0,0 +1,4 @@
+nav:
+  - overview.md
+  - permissions.md
+  - ...