From a845e0fcdebb172903d4fdaf23cce231bc7e0beb Mon Sep 17 00:00:00 2001 From: Stephan Lo Date: Tue, 5 Nov 2024 09:38:29 +0100 Subject: [PATCH 1/2] chore(hugo): Added devbox for hugo processing. Improved README documentation. --- README.md | 73 +++++++++++++++++++++----------- devbox.json | 11 +++++ devbox.lock | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+), 24 deletions(-) create mode 100644 devbox.json create mode 100644 devbox.lock diff --git a/README.md b/README.md index 7e55b7a..b5e35bc 100644 --- a/README.md +++ b/README.md @@ -6,58 +6,83 @@ This repo contains business and architectural design and documentation of the De The documentation is done in [Hugo-format](https://gohugo.io). -The repo contains a [Hugo `.devcontainer`-defintion](https://containers.dev/) so that you just have to run locally an IDE which is devcontainer aware, e.g. Visual Studio code. +Hugo is a static site renderer - so to get the documentation site presented you need a running Hugo processor. Therefore there is -### Installation +* either a Hugo [`.devcontainer`-definition](https://containers.dev/) - just run a devcontainer aware IDE or CLI, e.g. Visual Studio code +* or a Hugo [`Devbox`-definition](https://www.jetify.com/devbox/) - in this case just run a devbox shell -To get a locally running documentation editing and presentation environment, follow these steps: +## Local installation of the Hugo documentation system + +We describe two possible ways (one with devcontainer, one with devbox) to get the Hugo-documentation system locally running. + +For both prepare the following three steps: 1. open a terminal on your local box -2. clone this repo: `git clone https://bitbucket.telekom-mms.com/scm/ipceicis/ipceicis-developerframework.git ` -3. change to the repo working dir: `cd ipceicis-developerframework` -4. open the repo in an [Devcontainer-aware tool/IDE](https://containers.dev/supporting) (e.g. `code .`) -5. start the `devcontainer` (in VSC it's `F1 + Reopen in Devcontainer`) -6. when the container is up & running just open your browser with `http://localhost:1313/` +2. clone this repo: `git clone https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation` +3. change to the repo working dir: `cd website-and-documentation` -If you want to run the devcontainer without VS Code, you can use npn to run it inside a docker container: +### Possibility 1: Hugo in a devcontainer -1. install Node.js (>= Version 14), npm and the docker engine -2. install the devcontainer cli: `npm install -g @devcontainers/cli` -3. change into the folder of this repo -4. start the devcontainer by running: `devcontainer up --workspace-folder .` -5. find out the IP address of the devconatiner by using `docker ps` and `docker inspect ` -6. when the container is up & running just open your browser with `http://:1313/` +[`devcontainers`](https://containers.dev/) are running containers as virtual systems on your local box. The defintion is in the `.devcontainer` folder. +Thus as preliminary you need a container daemon running, e.g. Docker. -### Editing +There are several options to create and run the devcontainer - we present here two: -#### Documentation language +#### Option 1: Run the container triggered by and connected to an IDE, e.g. VS Code + +1. open the repo in an [Devcontainer-aware tool/IDE](https://containers.dev/supporting) (e.g. `code .`) +1. start the `devcontainer` (in VSC it's `F1 + Reopen in Devcontainer`) +1. when the container is up & running just open your browser with `http://localhost:1313/` + +#### Option 2: Run the container natively + +An alternative to get the container image is the [devcontainer CLI](https://github.com/devcontainers/cli), then you can run the devcontainer without VS Code. +Thus as preliminary you need to do the install steps of the devconatiner cli. + +1. start the devcontainer by running: `devcontainer up --workspace-folder .` +1. find out the IP address of the devconatiner by using `docker ps` and `docker inspect ` +1. when the container is up & running just open your browser with `http://:1313/` + +### Possibility 2: Hugo in a devbox + +[`Devboxes`](https://www.jetify.com/devbox/) are locally isolated environments, managed by the [Nix package manager](https://nix.dev/). So first [prepare the devbox](https://www.jetify.com/docs/devbox/installing_devbox/). + +Then + +1. ```devbox shell``` +1. In the shell: ```hugo serve``` + + +## Editing + +### Documentation language The documentation is done in [Docsy-Theme](https://www.docsy.dev/). So for editing content just goto the `content`-folder and edit content arrording to the [Docsy documentation](https://www.docsy.dev/docs/adding-content/) -### Commiting +## Commiting After having finished a unit of work commit and push. -## Annex +# Annex -### Installation steps illustrated +## Installation steps illustrated When you run the above installation, the outputs could typically look like this: -#### Steps 4/5 in Visual Studio Code +### In Visual Studio Code -##### Reopen in Container +#### Reopen in Container ![vsc-f1](./assets/images/vsc-f1.png) -##### Hugo server is running and (typically) listens to localhost:1313 +#### Hugo server is running and (typically) listens to localhost:1313 After some installation time you have: ![vsc-hugo](./assets/images/vsc-hugo.png) -#### Steps 6 in a web browser +### Final result in a web browser ![browser](./assets/images/browser.png) diff --git a/devbox.json b/devbox.json new file mode 100644 index 0000000..9d41ba3 --- /dev/null +++ b/devbox.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.10.5/.schema/devbox.schema.json", + "packages": [ + "hugo@0.125.4", + "dart-sass@1.75.0" + ], + "shell": { + "init_hook": [], + "scripts": {} + } +} diff --git a/devbox.lock b/devbox.lock new file mode 100644 index 0000000..71ceb09 --- /dev/null +++ b/devbox.lock @@ -0,0 +1,117 @@ +{ + "lockfile_version": "1", + "packages": { + "dart-sass@1.75.0": { + "last_modified": "2024-05-03T15:42:32Z", + "resolved": "github:NixOS/nixpkgs/5fd8536a9a5932d4ae8de52b7dc08d92041237fc#dart-sass", + "source": "devbox-search", + "version": "1.75.0", + "systems": { + "aarch64-darwin": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/6ynzjs0v55h88ri86li1d9nyr822n7kk-dart-sass-1.75.0", + "default": true + }, + { + "name": "pubcache", + "path": "/nix/store/f4wbni4cqdhq8y9phl6aazyh54mnacz7-dart-sass-1.75.0-pubcache" + } + ], + "store_path": "/nix/store/6ynzjs0v55h88ri86li1d9nyr822n7kk-dart-sass-1.75.0" + }, + "aarch64-linux": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/g88isq3r0zpxvx1rzc86dl9ny15jr980-dart-sass-1.75.0", + "default": true + }, + { + "name": "pubcache", + "path": "/nix/store/l6vdyb4i5hb9qmvms9v9g7vsnynfq0lb-dart-sass-1.75.0-pubcache" + } + ], + "store_path": "/nix/store/g88isq3r0zpxvx1rzc86dl9ny15jr980-dart-sass-1.75.0" + }, + "x86_64-darwin": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/h79n1apvmgpvw4w855zxf9qx887k9v3d-dart-sass-1.75.0", + "default": true + }, + { + "name": "pubcache", + "path": "/nix/store/bxmfb2129kn4xnrz5i4p4ngkplavrxv4-dart-sass-1.75.0-pubcache" + } + ], + "store_path": "/nix/store/h79n1apvmgpvw4w855zxf9qx887k9v3d-dart-sass-1.75.0" + }, + "x86_64-linux": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/yvr71pda4bm9a2dilgyd77297xx32iad-dart-sass-1.75.0", + "default": true + }, + { + "name": "pubcache", + "path": "/nix/store/h8n6s7f91kn596g2hbn3ccbs4s80bm46-dart-sass-1.75.0-pubcache" + } + ], + "store_path": "/nix/store/yvr71pda4bm9a2dilgyd77297xx32iad-dart-sass-1.75.0" + } + } + }, + "hugo@0.125.4": { + "last_modified": "2024-04-27T02:17:36Z", + "resolved": "github:NixOS/nixpkgs/698fd43e541a6b8685ed408aaf7a63561018f9f8#hugo", + "source": "devbox-search", + "version": "0.125.4", + "systems": { + "aarch64-darwin": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/2ssds5l4s15xfgljv2ygjhqpn949lxj4-hugo-0.125.4", + "default": true + } + ], + "store_path": "/nix/store/2ssds5l4s15xfgljv2ygjhqpn949lxj4-hugo-0.125.4" + }, + "aarch64-linux": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/nln80v8vsw5h3hv7kihglb12fy077flb-hugo-0.125.4", + "default": true + } + ], + "store_path": "/nix/store/nln80v8vsw5h3hv7kihglb12fy077flb-hugo-0.125.4" + }, + "x86_64-darwin": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/n6az4gns36nrq9sbiqf2kf7kgn1kjyfm-hugo-0.125.4", + "default": true + } + ], + "store_path": "/nix/store/n6az4gns36nrq9sbiqf2kf7kgn1kjyfm-hugo-0.125.4" + }, + "x86_64-linux": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/k53ijl83p62i6lqia2jjky8l136x42i7-hugo-0.125.4", + "default": true + } + ], + "store_path": "/nix/store/k53ijl83p62i6lqia2jjky8l136x42i7-hugo-0.125.4" + } + } + } + } +} From 0ada8f00be2058eadf2f373ee7a30f6f7c7129cb Mon Sep 17 00:00:00 2001 From: Stephan Lo Date: Thu, 7 Nov 2024 12:55:07 +0100 Subject: [PATCH 2/2] chore(devbox): added go dependency --- devbox.json | 3 ++- devbox.lock | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) diff --git a/devbox.json b/devbox.json index 9d41ba3..a5adc5a 100644 --- a/devbox.json +++ b/devbox.json @@ -2,7 +2,8 @@ "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.10.5/.schema/devbox.schema.json", "packages": [ "hugo@0.125.4", - "dart-sass@1.75.0" + "dart-sass@1.75.0", + "go@latest" ], "shell": { "init_hook": [], diff --git a/devbox.lock b/devbox.lock index 71ceb09..c009b13 100644 --- a/devbox.lock +++ b/devbox.lock @@ -65,6 +65,54 @@ } } }, + "go@latest": { + "last_modified": "2024-10-13T23:44:06Z", + "resolved": "github:NixOS/nixpkgs/d4f247e89f6e10120f911e2e2d2254a050d0f732#go", + "source": "devbox-search", + "version": "1.23.2", + "systems": { + "aarch64-darwin": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/35jikx2wg5r0qj47sic0p99bqnmwi6cn-go-1.23.2", + "default": true + } + ], + "store_path": "/nix/store/35jikx2wg5r0qj47sic0p99bqnmwi6cn-go-1.23.2" + }, + "aarch64-linux": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/6bx6d90kpy537yab22wja70ibpp4gkww-go-1.23.2", + "default": true + } + ], + "store_path": "/nix/store/6bx6d90kpy537yab22wja70ibpp4gkww-go-1.23.2" + }, + "x86_64-darwin": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/yi89mimkmw48qhzrll1aaibxbvllpsjv-go-1.23.2", + "default": true + } + ], + "store_path": "/nix/store/yi89mimkmw48qhzrll1aaibxbvllpsjv-go-1.23.2" + }, + "x86_64-linux": { + "outputs": [ + { + "name": "out", + "path": "/nix/store/klw1ipjsqx1np7pkk833x7sad7f3ivv9-go-1.23.2", + "default": true + } + ], + "store_path": "/nix/store/klw1ipjsqx1np7pkk833x7sad7f3ivv9-go-1.23.2" + } + } + }, "hugo@0.125.4": { "last_modified": "2024-04-27T02:17:36Z", "resolved": "github:NixOS/nixpkgs/698fd43e541a6b8685ed408aaf7a63561018f9f8#hugo",