From 500845ab8ef865d16d22a59b903e6eeab2334034 Mon Sep 17 00:00:00 2001 From: Joey Hafner Date: Tue, 31 Dec 2024 10:43:39 -0800 Subject: [PATCH] Docs: update formatting --- .sops/README.md | 30 +++++++++++++++--------------- README.md | 18 +++++++++--------- 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/.sops/README.md b/.sops/README.md index a98f88fe..401406b4 100644 --- a/.sops/README.md +++ b/.sops/README.md @@ -1,23 +1,23 @@ # sops Encryption/Decryption Workflow in Git -1. The user creates a file called `secrets.env` anywhere in the repository. This file is [dotenv-formatted](https://stackoverflow.com/questions/68267862/what-is-an-env-or-dotenv-file-exactly) as simple key-value pairs where the value is a secret to be passed into a Stack or container. We want to be able to read the "shape" of the file (the names of the keys), even when the file is encrypted. -2. The [`.gitattributes`](.gitattributes) file assignes the following properties to files called `secrets.env`: - 1. `filter=sops` which tells the local git instance to run the "sops" filter configured in [`.git/config`](/.git/config). - 2. `diff=sops` which tells the local git instance to run the "sops" diff command instead of the normal `git diff` when diffing `secrets.env` files. -3. The [`.git/config`](/.git/config) is configured with the "sops" filter and diff blocks referenced above. - 1. `filter.sops.smudge=` will run the thing after the `=` when checking out the repository. This should decrypt our secrets, making them "dirty" again. We call [`decrypt-filter.sh`](/.sops/decrypt-filter.sh) and pass `%f` as a positional argument, which renders to the path of the file being filtered, relative to the repo root (e.g. `homelab/stacks/books/secrets.env`). - 2. `filter.sops.clean=` will run the thing after the `=` when staging changes to commit. This should encrypt our secrets, making them "clean". We call [`encrypt-filter.sh`](/.sops/decrypt-filter.sh) and pass `%f` as a positional argument, which renders to the path of the file being filtered, relative to the repo root (e.g. `homelab/stacks/books/secrets.env`). +1. The user creates a file called `secrets.env` anywhere in the repository. This file is [dotenv-formatted](https://stackoverflow.com/questions/68267862/what-is-an-env-or-dotenv-file-exactly) as simple key-value pairs where the value is a secret to be passed into a Stack or container. We want to be able to read the "shape" of the file (the names of the keys), even when the file is encrypted. +2. The [`.gitattributes`](.gitattributes) file assigns the following properties to files called `secrets.env`: + 1. `filter=sops` which tells the local git instance to run the "sops" filter configured in [`.git/config`](/.git/config). + 2. `diff=sops` which tells the local git instance to run the "sops" diff command instead of the normal `git diff` when diffing `secrets.env` files. +3. The [`.git/config`](/.git/config) is configured with the "sops" filter and diff blocks referenced above. + 1. `filter.sops.smudge=` will run the thing after the `=` when checking out the repository. This should decrypt our secrets, making them "dirty" again. We call [`decrypt-filter.sh`](/.sops/decrypt-filter.sh) and pass `%f` as a positional argument, which renders to the path of the file being filtered, relative to the repo root (e.g. `homelab/stacks/books/secrets.env`). + 2. `filter.sops.clean=` will run the thing after the `=` when staging changes to commit. This should encrypt our secrets, making them "clean". We call [`encrypt-filter.sh`](/.sops/decrypt-filter.sh) and pass `%f` as a positional argument, which renders to the path of the file being filtered, relative to the repo root (e.g. `homelab/stacks/books/secrets.env`). 3. `filter.sops.required=true` will ensure that if the scripts fail, the commit will error out. - 4. `diff.sops.textconv=` will use the command after the `=` instead of `git diff` when comparing files. This affects whether files are considered "modified". + 4. `diff.sops.textconv=` will use the command after the `=` instead of `git diff` when comparing files. This affects whether files are considered "modified". 4. When the user stages a new `secrets.env` file at `homelab/stacks/books/secrets.env`, we automatically run `encrypt.sh homelab/stacks/books/secrets.env`. This implictly passes the contents of `secrets.env` to the script at `/dev/stdin`. The script takes the following steps to generate the encrypted content of the file: - 1. Assert privatekey existence at `~/.age/key`. - 2. Determine file extension. For now, we're only working with dotenv-formatted files, but sometimes we also need to support binary files. We use this information to set the `--input-type` parameter. + 1. Assert privatekey existence at `~/.age/key`. + 2. Determine file extension. For now, we're only working with dotenv-formatted files, but sometimes we also need to support binary files. We use this information to set the `--input-type` parameter. 3. Encrypt the file contents. This command infers recipients from [`.sops.yaml`](/.sops.yaml). The command uses the privatekey (at `~/.age/key`) of the local user to encrypt the secret. We use [Shamir's secret sharing](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing) with [sops key groups](https://github.com/getsops/sops?tab=readme-ov-file#215key-groups) to require *at least two of*: author key, CI/CD key, and deploy key. Of course, the original privatekey can always decrypt the secret. -5. Our new `secrets.env` file is committed to the repository. Encrypted and json-formatted ([why not dotenv-formatted?](https://github.com/getsops/sops/issues/857#issuecomment-2307658865)). -6. Now we want to deploy our new `homelab/stacks/books` Stack. We'll focus on the sops-related aspects of this process. +5. Our new `secrets.env` file is committed to the repository. Encrypted and json-formatted ([why not dotenv-formatted?](https://github.com/getsops/sops/issues/857#issuecomment-2307658865)). +6. Now we want to deploy our new `homelab/stacks/books` Stack. We'll focus on the sops-related aspects of this process. 1. Our CI/CD environment is configured with an age keypair. Additional CI/CD environments will each be configured with their own keypairs. - 2. Our deploy environments (hosts) are each configured with an age keypair. - 3. Our [CI/CD script](/.gitea/workflows/homelab_deploy-compose-stack.yml) is configured to decrypt secrets and export the variables before bringing up the Stack. + 2. Our deploy environments (hosts) are each configured with an age keypair. + 3. Our [CI/CD script](/.gitea/workflows/homelab_deploy-compose-stack.yml) is configured to decrypt secrets and export the variables before bringing up the Stack. ### List Files Managed by sops @@ -27,4 +27,4 @@ git ls-files |\ git check-attr -a --stdin |\ grep 'filter: sops' |\ cut -d':' -f1 -``` \ No newline at end of file +``` diff --git a/README.md b/README.md index 1460e70a..e1214485 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,19 @@ -# Jafner.net +# Jafner.net A monorepo for all my projects and dotfiles. Hosted on [my Gitea](https://gitea.jafner.tools/Jafner/Jafner.net) and mirrored to [GitHub](https://github.com/Jafner/Jafner.net). ## Map of Contents | Project | Summary | |:----------------------:|:-------:| -| [dotfiles](/dotfiles/) | Configuration and documentation for my PCs. | -| [homelab](/homelab/) | Configuration and documentation for my homelab. | -| [projects](/projects/) | Self-contained projects in a variety of scripting and programming languages. | -| [sites](/sites/) | Static site files | -| [.gitea/workflows](/.gitea/workflows/) & [.github/workflows](/.github/workflows/) | GitHub Actions workflows running on [Gitea](https://gitea.jafner.tools/Jafner/Jafner.net/actions) and [GitHub](https://github.com/Jafner/Jafner.net/actions), respectively. | -| [.sops](/.sops/) | Scripts and documentation implementing [sops](https://github.com/getsops/sops) to securely store secrets in this repo. | +| [dotfiles](dotfiles/) | Configuration and documentation for my PCs. | +| [homelab](homelab/) | Configuration and documentation for my homelab. | +| [projects](projects/) | Self-contained projects in a variety of scripting and programming languages. | +| [sites](sites/) | Static site files | +| [.gitea/workflows](.gitea/workflows/) & [.github/workflows](.github/workflows/) | GitHub Actions workflows running on [Gitea](https://gitea.jafner.tools/Jafner/Jafner.net/actions) and [GitHub](https://github.com/Jafner/Jafner.net/actions), respectively. | +| [.sops](.sops/) | Scripts and documentation implementing [sops](https://github.com/getsops/sops) to securely store secrets in this repo. | ## LICENSE: MIT License -> See [LICENSE](/LICENSE) for details. +> See [LICENSE](LICENSE) for details. ## Contributing -Presently this project is a one-man operation with no external contributors. All contributions will be addressed in good faith on a best-effort basis. \ No newline at end of file +Presently this project is a one-man operation with no external contributors. All contributions will be addressed in good faith on a best-effort basis.