Jafner/Jafner.net
1
0
Fork 0
Code Issues 16 Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: update formatting

Browse Source
This commit is contained in:
Joey Hafner 2024-12-31 10:43:39 -08:00
parent bc9494c01a
commit 500845ab8e
Signed by: Jafner
GPG Key ID: 6D9A24EF2F389E55
2 changed files with 24 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
.sops/README.md
View File

@ -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
```
```

18
README.md
View File

@ -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.
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.