Merge pull request #31 from superfly/book

Basic mdbook structure and _some_ docs

.github/workflows/book.yml

@@ -0,0 +1,39 @@
+name: Book
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: mdbook,mdbook-linkcheck
+
+      - name: Build Book
+        run: mdbook build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: 'book'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/ci.yml

@@ -11,37 +11,55 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-    build:
-      name: Test
-      strategy:
-        fail-fast: false
-        matrix:
-          include:
-            - target: x86_64-apple-darwin
-              os: macos-latest
-            - target: x86_64-unknown-linux-gnu
-              os: ubuntu-latest
-
-      runs-on: ${{ matrix.os }}
+  test:
+    name: Test
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-apple-darwin
+            os: macos-latest
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: rui314/setup-mold@v1
 
-      steps:
-        - uses: actions/checkout@v3
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          target: ${{ matrix.target }}
 
-        - uses: rui314/setup-mold@v1
+      - name: Install cargo-nextest
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-nextest
 
-        - name: Install Rust stable
-          uses: dtolnay/rust-toolchain@stable
-          with:
-            target: ${{ matrix.target }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      - name: Test with latest nextest release
+        run: cargo nextest run --profile ci --workspace --target ${{ matrix.target }}
+
+  book-test:
+    name: Build book
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pull-requests: write  # To create a PR from that branch
+    steps:
+      - uses: actions/checkout@master
+
+      - uses: dtolnay/rust-toolchain@stable
 
-        - name: Install cargo-nextest
-          uses: taiki-e/install-action@v2
-          with:
-            tool: cargo-nextest
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: mdbook,mdbook-linkcheck
 
-        - uses: Swatinem/rust-cache@v2
-          with:
-            cache-on-failure: true
-
-        - name: Test with latest nextest release
-          run: cargo nextest run --profile ci --workspace --target ${{ matrix.target }}
+      - name: Build Book
+        run: mdbook build

.gitignore

@@ -1,4 +1,5 @@
 /target
 /schema
 /config.toml
-/data
+/data
+/book

book.toml

@@ -0,0 +1,10 @@
+[book]
+authors = ["Jerome Gravel-Niquet"]
+language = "en"
+multilingual = false
+src = "doc"
+title = "Corrosion"
+
+[output.html]
+
+[output.linkcheck]

crates/corro-types/src/config.rs

@@ -95,12 +95,12 @@ pub struct TlsConfig {
     #[serde(default)]
     pub ca_file: Option<Utf8PathBuf>,
 
-    /// Mutual TLS configuration
     #[serde(default)]
-    pub client: Option<TlsClientConfig>,
+    pub insecure: bool,
 
+    /// Mutual TLS configuration
     #[serde(default)]
-    pub insecure: bool,
+    pub client: Option<TlsClientConfig>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]

crates/corrosion/src/command/tls.rs

@@ -1,13 +1,14 @@
 use std::{net::IpAddr, path::Path};
 
+use camino::Utf8PathBuf;
 use tokio::io::AsyncWriteExt;
 use tracing::info;
 
 pub async fn generate_ca<P: AsRef<Path>>(output_path: P) -> eyre::Result<()> {
     let cert = corro_types::tls::generate_ca()?;
 
-    let cert_path = output_path.as_ref().join("ca.pem");
-    let key_path = output_path.as_ref().join("ca.key");
+    let cert_path = output_path.as_ref().join("ca_cert.pem");
+    let key_path = output_path.as_ref().join("ca_key.pem");
 
     let cert_pem = cert.serialize_pem();
     let mut cert_file = tokio::fs::File::create(&cert_path).await?;
@@ -40,18 +41,22 @@ pub async fn generate_server_cert<P1: AsRef<Path>, P2: AsRef<Path>>(
     let (cert, cert_signed) =
         corro_types::tls::generate_server_cert(&ca_cert_pem, &ca_key_pem, ip)?;
 
-    let mut cert_file = tokio::fs::File::create("cert.pem").await?;
+    let cert_file_path = Utf8PathBuf::from("server_cert.pem");
+
+    let mut cert_file = tokio::fs::File::create(&cert_file_path).await?;
     cert_file.write_all(cert_signed.as_bytes()).await?;
 
-    info!("Wrote server certificate to ./cert.pem");
+    info!("Wrote server certificate to {cert_file_path}");
+
+    let key_file_path = Utf8PathBuf::from("server_key.pem");
 
     let private_key_pem = cert.serialize_private_key_pem();
-    let mut private_key_file = tokio::fs::File::create("cert.key").await?;
+    let mut private_key_file = tokio::fs::File::create(&key_file_path).await?;
     private_key_file
         .write_all(private_key_pem.as_bytes())
         .await?;
 
-    info!("Wrote server key to ./cert.key");
+    info!("Wrote server key to {key_file_path}");
 
     Ok(())
 }
@@ -68,18 +73,22 @@ pub async fn generate_client_cert<P1: AsRef<Path>, P2: AsRef<Path>>(
 
     let (cert, cert_signed) = corro_types::tls::generate_client_cert(&ca_cert_pem, &ca_key_pem)?;
 
-    let mut cert_file = tokio::fs::File::create("client-cert.pem").await?;
+    let cert_file_path = Utf8PathBuf::from("client_cert.pem");
+
+    let mut cert_file = tokio::fs::File::create(&cert_file_path).await?;
     cert_file.write_all(cert_signed.as_bytes()).await?;
 
     info!("Wrote client certificate to ./client-cert.pem");
 
+    let key_file_path = Utf8PathBuf::from("client_key.pem");
+
     let private_key_pem = cert.serialize_private_key_pem();
-    let mut private_key_file = tokio::fs::File::create("client-cert.key").await?;
+    let mut private_key_file = tokio::fs::File::create(&key_file_path).await?;
     private_key_file
         .write_all(private_key_pem.as_bytes())
         .await?;
 
-    info!("Wrote client key to ./client-key.pem");
+    info!("Wrote client key to {key_file_path}");
 
     Ok(())
 }

doc/SUMMARY.md

@@ -0,0 +1,26 @@
+# Summary
+
+[Introduction](intro.md)
+
+# User guide
+- [Operations Guide]()
+
+# Reference
+- [Command-line Interface](cli/README.md)
+    - [agent]()
+    - [backup](cli/backup.md)
+    - [consul]()
+    - [exec]()
+    - [query]()
+    - [reload]()
+    - [restore](cli/restore.md)
+    - [sync]()
+    - [template]()
+    - [tls](cli/tls.md)
+- [Configuration](config/README.md)
+    - [db]()
+    - [gossip](config/gossip.md)
+    - [api]()
+    - [admin]()
+    - [telemetry]()
+    - [consul]()

doc/cli/README.md

@@ -0,0 +1,5 @@
+# Command-line Interface
+
+See the chapters for each subcommand:
+- [`corrosion backup`](backup.md)
+- [`corrosion restore`](restore.md)

doc/cli/backup.md

@@ -0,0 +1,20 @@
+# The `corrosion backup` command
+
+Creates a backup of the current database by running `VACUUM INTO` and cleaning up node-specific data. This includes removing `crsql_site_id` as well as rewriting `__crsql_clock` tables to make the backup generic, ready for a `corrosion restore`.
+
+```
+$ corrosion backup --help
+Backup the Corrosion DB
+
+Usage: corrosion backup [OPTIONS] <PATH>
+
+Arguments:
+  <PATH>
+
+Options:
+  -c, --config <CONFIG_PATH>     Set the config file path [default: corrosion.toml]
+      --api-addr <API_ADDR>
+      --db-path <DB_PATH>
+      --admin-path <ADMIN_PATH>
+  -h, --help                     Print help
+```

doc/cli/restore.md

@@ -0,0 +1,20 @@
+# The `corrosion restore` command
+
+Restores a database from a backup produced by `corrosion backup`. This is an "online restore", it acquires all the appropriate locks on the sqlite3 database so as to not disrupt database readers. It then replaces the database in-place and releases the locks.
+
+```
+$ corrosion restore --help
+Restore the Corrosion DB from a backup
+
+Usage: corrosion restore [OPTIONS] <PATH>
+
+Arguments:
+  <PATH>
+
+Options:
+  -c, --config <CONFIG_PATH>     Set the config file path [default: corrosion.toml]
+      --api-addr <API_ADDR>
+      --db-path <DB_PATH>
+      --admin-path <ADMIN_PATH>
+  -h, --help                     Print help
+```

doc/cli/tls.md

@@ -0,0 +1,62 @@
+# The `corrosion tls` command
+
+In non-development environment, you'll want to configure `[gossip.tls]` to secure the transport of information within the cluster.
+
+```
+$ corrosion tls --help
+Tls-related commands
+
+Usage: corrosion tls [OPTIONS] <COMMAND>
+
+Commands:
+  ca      TLS certificate authority commands
+  server  TLS server certificate commands
+  client  TLS client certificate commands (for mutual TLS)
+  help    Print this message or the help of the given subcommand(s)
+```
+
+## `corrosion tls ca generate`
+
+A CA (Certificate Authority) is necessary to sign server certificates. It's expected for a Corrosion cluster to have a single CA key pair for signing all the nodes' server certificates.
+
+**Store the key somewhere secure!**
+
+```toml
+$ corrosion tls ca generate --help
+Generate a TLS certificate authority
+
+Usage: corrosion tls ca generate [OPTIONS]
+```
+
+By default, certificates will be output as `ca_cert.pem` and `ca_key.pem` in the current directory.
+
+## `corrosion tls server generate`
+
+Generates a server certificate key pair for encrypting peer-to-peer packets. To be used in the `gossip.tls` configuration block.
+
+The command accepts a `<IP>` positional argument, it needs to be the IP address your cluster's nodes will use for connecting to the server you're generating the certificates for.
+
+You'll need to have previously generated a CA key pair as it's required to pass `--ca-key` and `--ca-cert` flags w/ paths to each PEM file respectively.
+
+```
+$ corrosion tls server generate --help
+Generate a TLS server certificate from a CA
+
+Usage: corrosion tls server generate [OPTIONS] --ca-key <CA_KEY> --ca-cert <CA_CERT> <IP>
+
+Arguments:
+  <IP>
+```
+
+## `corrosion tls client generate`
+
+Generates a client certificate key pair to authorizing peer-to-peer clients.
+
+You'll need to have previously generated a CA key pair as it's required to pass `--ca-key` and `--ca-cert` flags w/ paths to each PEM file respectively.
+
+```
+$ corrosion tls client generate
+Generate a TLS certificate from a CA
+
+Usage: corrosion tls client generate [OPTIONS] --ca-key <CA_KEY> --ca-cert <CA_CERT>
+```

doc/config/README.md

@@ -0,0 +1 @@
+# Configuration