diff --git a/docs/config.toml b/docs/config.toml index 53adace..47dc75e 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -1,18 +1,53 @@ baseURL = 'https://certwarden-deploy.adora.codes/' languageCode = 'en-us' title = 'certwarden-deploy' +author = "" -theme = "code.lila.network/adoralaura/hugo-book-theme" +theme = "github.com/McShelby/hugo-theme-relearn" +repo = "https://code.lila.network/adoralaura/certwarden-deploy" +enableGitInfo = true +enableRobotsTXT = true +uniqueHomePage = false # change to false to add sidebar to homepage [params] - # (Optional, default light) Sets color theme: light, dark or auto. - # Theme 'auto' switches between dark and light modes based on browser/os preferences - BookTheme = 'auto' - BookRepo = 'https://code.lila.network/adoralaura/certwarden-deploy' + disableLandingPageButton = false + disableLanguageSwitchingButton = false + editURL = "https://code.lila.network/adoralaura/certwarden-deploy/_edit/main/docs/content/${FilePath}" + externalLinkTarget = "_blank" -[module] - [[module.imports]] - path = "code.lila.network/adoralaura/hugo-book-theme" +[params.author] + name = 'Adora Laura Kalb' + +[outputs] + home = ['html', 'rss', 'search'] + +[menu] + [[menu.shortcuts]] + identifier = 'ds' + name = " certwarden-deploy Git Repository" + url = 'https://code.lila.network/adoralaura/certwarden-deploy' + weight = 10 + + [[menu.shortcuts]] + name = " CertWarden GitHub" + url = 'showcase/' + weight = 11 + + [[menu.shortcuts]] + identifier = 'hugodoc' + name = " CertWarden Website" + url = 'https://gohugo.io/' + weight = 20 + +# [[menu.shortcuts]] +# name = " Credits" +# url = 'more/credits/' +# weight = 30 +# +# [[menu.shortcuts]] +# name = " Tags" +# url = 'tags/' +# weight = 40 diff --git a/docs/content/_index.md b/docs/content/_index.md index d7089b9..0489d0c 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -1,10 +1,8 @@ --- -title: Introduction +title: CertWarden-Deploy type: docs --- -## CertWarden - [CertWarden](https://www.certwarden.com/) is a self-hosted Centralized ACME Certificate Management platform. With it you can manage and aquire Let's Encrypt certificates. However, to deploy them to your hosts, for now there only was a docker client, and that was too bloated for me. @@ -27,9 +25,9 @@ sudo chmod +x /usr/local/bin/certwarden-deploy ``` ... fill out the config file... -```shell -vi /etc/certwarden-deploy/config.yaml -``` + + +`vi /etc/certwarden-deploy/config.yaml` ```yaml # Base URL of the CertWarden instance # required @@ -79,7 +77,7 @@ I use my own [Forgejo](https://forgejo.org/) Instance [code.lila.network](https: * If you have a trivial fix or improvement, go ahead and send a diff to the maintainer(s) of this repository (see [MAINTAINERS.md](https://code.lila.network/adoralaura/certwarden-deploy/src/branch/main/MAINTAINERS.md)). -* If you plan to do something more involved, first please [send me a mail]( mailto:dev@lauka.net?subject=%5Bcertwarden-deploy%5D)mso I can create an account for you. +* If you plan to do something more involved, first please [send me a mail](mailto:dev@lauka.net?subject=%5Bcertwarden-deploy%5D) so I can create an account for you. ### Non-development Contibutions @@ -92,4 +90,4 @@ share what works. You can find the Changelog here: [Changelog](https://code.lila.network/adoralaura/certwarden-deploy/src/branch/main/CHANGELOG.md) ## License -`certwarden-deploy` is available under the MIT license. See the [LICENSE](https://code.lila.network/adoralaura/certwarden-deploy/src/branch/main/LICENSE) file for more info. +`certwarden-deploy` is available under the MIT license. See the [License page](/license/) for more info. diff --git a/docs/content/configuration.md b/docs/content/configuration.md new file mode 100644 index 0000000..493cfd4 --- /dev/null +++ b/docs/content/configuration.md @@ -0,0 +1,85 @@ +--- +title: Configuration +weight: 20 +--- + + +This document describes how to configure `certwarden-deploy` and which certificates should be managed by it. The configuration file uses the [YAML format](https://yaml.org/) for a human-readable and easy-to-maintain structure. + +## certwarden-deploy CLI Options +```plaintext +$ ./certwarden-deploy --help +certwarden-deploy is a CLI utility to deploy certificates managed by CertWarden. +Configuration is handled by a single YAML file, so you can get started quickly. + +For more information on how to configure this tool, visit the docs at https://certwarden-deploy.adora.codes + +Usage: + certwarden-deploy [flags] + +Flags: + -c, --config string Path to config file (default is /etc/certwarden-deploy/config.yaml) (default "/etc/certwarden-deploy/config.yaml") + -d, --dry-run Just show the would-be changes without changing the file system (turns on verbose logging) + -f, --force Force overwriting and execution action to occur, regardless if certificate already exists + -h, --help help for certwarden-deploy + -q, --quiet Disable any logging (if both -q and -v are set, quiet wins) + -v, --verbose Enable verbose logging + --version version for certwarden-deploy +``` + +## Configuration File Options + +`base_url` (required): +This string specifies the base URL of your CertWarden instance. + +`disable_certificate_validation` (optional, default: false): + This boolean flag indicates whether to disable certificate validation for the CertWarden instance. Set this to true only if your CertWarden instance uses a self-signed certificate and you trust it explicitly. **Disabling validation weakens security, so use it with caution.** + +`certificates:` (required): + This is a list that defines each certificate to be managed. + Each certificate definition is a nested YAML block with the following properties: + +Each certificate configuration consists of: + +`name` (required): +This string is a unique identifier for the certificate and must be the same as in you CertWarden instance. +It must start and end with an alphanumeric character and can contain letters (a-zA-Z), numbers (0-9), underscore (_), hyphen (-), and period (.). + +`cert_secret` (required): +This string holds the API key used to fetch the certificate data from the CertWarden server. + +`cert_path` (required): +This string defines the file path where the downloaded certificate will be saved. + +`key_secret` (required): +This string holds the API key used to fetch the private key data from the CertWarden server. + +`key_path` (required): +This string defines the file path where the downloaded private key will be saved. + +`action` (optional): +This string specifies a command to run after a certificate is updated or when the --force flag is used during execution. +The example uses a systemd reload command for the popular reverse named "caddy". + +Example Configuration: +```yaml +# Base URL of the CertWarden instance +base_url: "https://certwarden.example.com" + +# Disable certificate validation (not recommended for production) +disable_certificate_validation: false + +# Define all managed certificates here +certificates: + - name: test-certificate.example.com + cert_secret: examplekey_notvalid_hrzjGDDw8z # Replace with your actual key + cert_path: "/path/to/test-certificate.example.com-cert.pem" + key_secret: examplekey_notvalid_hrzbbDDw8z # Replace with your actual key + key_path: "/path/to/test-certificate.example.com-key.pem" + action: "/usr/bin/systemctl reload caddy" +``` +Use code with caution. + +## Notes +- This documentation assumes you have a basic understanding of YAML syntax. Resources for learning YAML are readily available online. +- Replace placeholder values like examplekey_notvalid_hrzjGDDw8z with your actual API keys. diff --git a/docs/content/installation.md b/docs/content/installation.md new file mode 100644 index 0000000..d0c504f --- /dev/null +++ b/docs/content/installation.md @@ -0,0 +1,30 @@ +--- +title: Installation +weight: 10 +--- + +## Prerequisites + +Before building the project, ensure you have the following installed: +- make: A build automation tool +- Go: Version 1.22 or later + +## Building the Project from Source + +To build the project, first clone the projects git repository, then navigate to the project's root directory and run the following command: +```shell +make build +``` +This command will generate the `certwarden-deploy` binary in the `bin/` folder. + +## Getting pre-built Binaries +You can also get pre-built binaries from the [releases page](https://code.lila.network/adoralaura/certwarden-deploy/releases). Make sure you get the binaries fitting your architecture! + +## Setting up automatic Certificate Renewals +Although not required for `certwarden-deploy` to work, it's highly rrecommended to set up automatic renewals for `certwarden-deploy`, so that you don't need to worry about rolling out your certificates every time they get renewed by CertWarden. + +To do that, there are example `systemd` Service and Timer files included in the `examples/` directory of the `certwarden-deploy` repository. + +Please make sure to customize them to your requirements (path to `certwarden-deploy` binary, user and group, execution interval...) and then drop them into the `/etc/systemd/system/` directory, then enable the timer with `systemctl enable --now certwarden-deploy.timer` + +If you kept the example schedule, `certwarden-deploy` will run every saturday at ~4am. diff --git a/docs/content/license.md b/docs/content/license.md new file mode 100644 index 0000000..d655ba4 --- /dev/null +++ b/docs/content/license.md @@ -0,0 +1,33 @@ +--- +title: License +weight: 99 +--- + +## Documentation +This documentation is available under the [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) + +## Source Code +The source code of `certwarden-deploy` is available under the MIT license: + +```plaintext +MIT License + +Copyright © 2024 Adora Laura Kalb + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the +Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, +INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +``` diff --git a/docs/content/menu/index.md b/docs/content/menu/index.md deleted file mode 100644 index ed418fe..0000000 --- a/docs/content/menu/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -headless: true ---- - -- [**Example Site**]({{< relref "/docs/example" >}}) -- [Table of Contents]({{< relref "/docs/example/table-of-contents" >}}) - - [With ToC]({{< relref "/docs/example/table-of-contents/with-toc" >}}) - - [Without ToC]({{< relref "/docs/example/table-of-contents/without-toc" >}}) -- [Collapsed]({{< relref "/docs/example/collapsed" >}}) - - [3rd]({{< relref "/docs/example/collapsed/3rd-level" >}}) - - [4th]({{< relref "/docs/example/collapsed/3rd-level/4th-level" >}}) -
- -- **Shortcodes** -- [Buttons]({{< relref "/docs/shortcodes/buttons" >}}) -- [Columns]({{< relref "/docs/shortcodes/columns" >}}) -- [Expand]({{< relref "/docs/shortcodes/expand" >}}) -- [Hints]({{< relref "/docs/shortcodes/hints" >}}) -- [KaTeX]({{< relref "/docs/shortcodes/katex" >}}) -- [Mermaid]({{< relref "/docs/shortcodes/mermaid" >}}) -- [Tabs]({{< relref "/docs/shortcodes/tabs" >}}) -
diff --git a/docs/go.mod b/docs/go.mod index a038a0f..68b6770 100644 --- a/docs/go.mod +++ b/docs/go.mod @@ -2,4 +2,4 @@ module code.lila.network/adoralaura/certwarden-deploy-docs go 1.22.2 -require code.lila.network/adoralaura/hugo-book-theme v0.0.0-20240712103017-55b1193ecd34 // indirect +require github.com/McShelby/hugo-theme-relearn v0.0.0-20240721222908-7aec99b38dc2 // indirect diff --git a/docs/go.sum b/docs/go.sum index 8829714..ea0937d 100644 --- a/docs/go.sum +++ b/docs/go.sum @@ -1,2 +1,2 @@ -code.lila.network/adoralaura/hugo-book-theme v0.0.0-20240712103017-55b1193ecd34 h1:jgwSyEijB5R4TxGxsO6Lugm1+bcaw7Tz5rCxptmc92A= -code.lila.network/adoralaura/hugo-book-theme v0.0.0-20240712103017-55b1193ecd34/go.mod h1:MBe0adh4WF9iMJ51BCRAeKkPUda/JB9RlGUQwmk5qc0= +github.com/McShelby/hugo-theme-relearn v0.0.0-20240721222908-7aec99b38dc2 h1:022HGVq2CBuTftLgNRiU3rxqh+w3M3ZcschnXbjgomc= +github.com/McShelby/hugo-theme-relearn v0.0.0-20240721222908-7aec99b38dc2/go.mod h1:mKQQdxZNIlLvAj8X3tMq+RzntIJSr9z7XdzuMomt0IM= diff --git a/docs/layouts/partials/logo.html b/docs/layouts/partials/logo.html new file mode 100644 index 0000000..448e87b --- /dev/null +++ b/docs/layouts/partials/logo.html @@ -0,0 +1 @@ + diff --git a/docs/static/images/favicon.ico b/docs/static/images/favicon.ico new file mode 100644 index 0000000..2ff2c4a Binary files /dev/null and b/docs/static/images/favicon.ico differ diff --git a/docs/static/images/logo.svg b/docs/static/images/logo.svg new file mode 100644 index 0000000..d2ab951 --- /dev/null +++ b/docs/static/images/logo.svg @@ -0,0 +1 @@ +certwarden-deploy \ No newline at end of file