diff --git a/doc/book.toml b/doc/book.toml index 55d153f..1bf1327 100644 --- a/doc/book.toml +++ b/doc/book.toml @@ -4,3 +4,11 @@ language = "en" multilingual = false src = "src" title = "ctrl" + +[output.html] +git-repository-url = "https://github.com/postmannen/ctrl" +git-repository-icon = "fa-github" + +[output.html.fold] +enable = false # whether or not to enable section folding +level = 0 # the depth to start folding diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 61c1c3c..61c2415 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -1,11 +1,14 @@ + # Introduction -- [introduction](./introduction.md) +- [Introduction](./introduction.md) +- [General information](./introduction_general_information.md) -# User Guide +# User Guides - [Install docker](./user_guide_install_docker.md) - [Install host](./user_guide_install_host.md) +- [Install NATS Server](./install_nats_server.md) # Core ctrl @@ -19,11 +22,15 @@ - [{{CTRL_FILE}} variable](./core_messaging_CTRL_FILE.md) - [Errors](./core_errors.md) -# Example standard messages +# Examples standard messages - [Http Get](./example_standard_reqhttpget.md) - [Tail File](./example_standard_reqtailfile.md) - [Cli Command](./example_standard_reqclicommand.md) - [Cli Command Continously](./example_standard_reqclicommandcont.md) - [Copy Src to Dst](./example_standard_reqcopysrc.md) -- [Send more messages at once](./example_standard_send_more_messages.md) \ No newline at end of file +- [Send more messages at once](./example_standard_send_more_messages.md) + +# Using ctrl + +- [ctrl as github action runner](usecase-ctrl-as-github-action-runner) \ No newline at end of file diff --git a/doc/src/install_nats_server.md b/doc/src/install_nats_server.md new file mode 100644 index 0000000..f6e2010 --- /dev/null +++ b/doc/src/install_nats_server.md @@ -0,0 +1,95 @@ +# NATS Server install + +ctrl uses NATS as the messagaging backbone. The following text will describe how to quickly get up and running with a minimal NATS setup. For full details of what you can do with nats-server, check out the official docs at [https://docs.nats.io/running-a-nats-service/introduction/installation](https://docs.nats.io/running-a-nats-service/introduction/installation) + +## NKEY + +NATS uses ED25519 based keys called NKEY's for Authentication and Authorization. The keys are created by a tool called **nk**. The instructions for how to install it are found here [https://docs.nats.io/using-nats/nats-tools/nk](https://docs.nats.io/using-nats/nats-tools/nk). + +The private key are called **seed**, and the public key are called **user**. + +To create the keys run the following command after the nk tool is installed. + +```bash +nk -gen user -pubout +``` + +The tool will print out two new keys. Where the private Seed starts with the letter ` S `, and the public User key starts with the letter ` U `. + +The private Seed key are used with each ctrl instance, and are referenced as an ENV, flag, or via file. + +The public User key are used in the nats-server config file for Authentication, to define access lists for what Nats Subjects the ctrl instances should be allowed to send to, or receive from. + +## Install the NATS Server + +For this example we use docker compose to start the NATS server. + +On your local computer create a folder to hold the NATS docker compose, and configuration files. + +```bash +mkdir nats && cd nats +``` + +create the docker compose file called `nats.yaml`, with the following content. + +```yaml +version: "3" + +services: + nats: + build: . + image: nats:latest + # -js enables jetstram on the nats server. + command: "-c /app/nats-server.conf -D -js" + restart: always + ports: + - "4222:4222" + volumes: + - ./nats.conf:/app/nats-server.conf + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "10" +``` + +In the same directory create the nats-server.conf file, with the following content. Replace the placeholders for the user keys in the acl with the user keys you created earlier. + +```json +port: 4222 + +ACL = { + publish: { + allow: [">"] + } + subscribe: { + allow: [">"] + } +} + +authorization: { + timeout: "30s" + users = [ + { + # github + nkey: + permissions: $ACL + }, + { + # node1 + nkey: + permissions: $ACL + }, + ] +} +``` + +## Firewall openings for NATS Server + +You will need to open your firewall for inbound `tcp/4222` from the internet. + +You can find your public ip address here [https://ipv4.jsonip.com/](https://ipv4.jsonip.com/). + +## Other + +More details like how to use certificates to encrypt the communication can be found in the official nats docs, [https://docs.nats.io/](https://docs.nats.io/). diff --git a/doc/src/introduction_general_information.md b/doc/src/introduction_general_information.md new file mode 100644 index 0000000..6cfe914 --- /dev/null +++ b/doc/src/introduction_general_information.md @@ -0,0 +1 @@ +# General information diff --git a/doc/src/usecase-ctrl-as-github-action-runner b/doc/src/usecase-ctrl-as-github-action-runner new file mode 100644 index 0000000..f5bcdb9 --- /dev/null +++ b/doc/src/usecase-ctrl-as-github-action-runner @@ -0,0 +1,138 @@ +# ctrl as github action runner + +Run ctrl as a docker container in a github workflow. This can for example be as part of a CI/CD pipeline, or for content versioning. + +This howto will show the steps involved to get ctrl up and running as Github Action Runner. First we start with setting up a NATS Server, we then setup the local ctrl node **node1**, and then the node that will be started as a Github Action Runner. + +This howto assumes that you have a nats-server setup, and at least one ctrl node instance up running. How to setup a **nats-server** and a **ctrl node** on a computer/server can be found in the **User Guides** section of the documentation. + +In the examples below I've used the name **node1** as an example for the node that will receive the message when the github repository are updated. + +## Github Action Runner setup + +Create a Github repository. + +Clone the repository down to your local machine or other. + +```bash +git clone && cd my-repo-name +``` + +Create a github workflows folder + +```bash +mkdir -p .github/workflows +``` + +Create a `workflow.yaml` in the new directory with the following content. + +```yaml +name: GitHub Actions Demo +run-name: ${{ github.actor }} is testing out GitHub Actions 🚀 +on: [push] + +jobs: + send-message: + name: send-message + runs-on: ubuntu-latest + + services: + ctrl: + image: postmannen/ctrl:amd64-0.03 + env: + NKEY_SEED: ${{ secrets.SEED }} + NODE_NAME: "github" + BROKER_ADDRESS: ":4222" + ENABLE_KEY_UPDATES: 0 + ENABLE_ACL_UPDATES: 0 + volumes: + # mount the readfolder where we put the message to send. + - ${{ github.workspace }}/readfolder:/app/readfolder + # mount the files folder from the repo to get the file + # to inject into the message. + - ${{ github.workspace }}/files:/app/files + options: --name ctrl + + steps: + # When the container was started the repo was not yeat available since it was not + # the workspace at that time. We want to make the /files mount to point to the + # folder in the repo. Checkout the git repo, and restart the docker container so + # it will mount the directories from the repo which now is the current github.workspace. + - name: checkout repo + uses: actions/checkout@v4 + - name: restart docker + uses: docker://docker + with: + args: docker restart ctrl + - run: sudo chmod 777 ${{ github.workspace }}/readfolder + - run: sleep 3 + # Send the message by moving it to the readfolder. + - run: mv ${{ github.workspace }}/message.yaml ${{ github.workspace }}/readfolder + - run: > + sleep 5 && tree +``` + +## Define NKEY as github secret + +In your repository, go to **Settings->Secrets And Variables->Actions** and press **New Repository Secret**. Give the new secret the name **SEED**, and put the content of the seed into **Secret**. This is the seed that we referenced earlier in the github action workflow. + +## Define message with command to send + +We want to send a message from the Github Action, so we need to specify the content of the message to use. + +In the root folder of the github folder create a **message.yaml** file, and fill in the following content: + +```yaml +--- +- toNodes: + - node1 + method: cliCommand + methodArgs: + - "bash" # Change from bash to ash for alpine containers + - "-c" + - | + echo '{{CTRL_FILE:./files/file.txt}}'>file.txt + + replyMethod: none + ACKTimeout: 0 +``` + +The message references a file with the `{{CTRL_FILE:}}` to use with the cli command found in the `files` folder. The file referenced will be embedded into the methodArgs defined in the message. + +From the repository folder run the following commands: + +```bash +mkdir -p files +echo "some cool text to put as file content.........." > files/file.txt +``` + +The example tries to show how we can get the message to run a shell/cli command on node1 at delivery. The shell command will use the content of the file located at `/files/file.txt`, and create a file called **file.txt** in the ctrl working directory on **node1**. + +## Update the repository and send message with command + +Commit the changes of the repository. If you check the **Actions** section of the new repo you should see that a an action have started. + +When the action is done, you should have received a file called **file.txt** in the ctrl working directory on **node1**, with the content you provided in **text.txt**. + +## Other cool things you can do ... like deploy kubernetes manifests + +Replace the the bash command specified in the method arguments with a kubetctl command like this: + +```yaml +--- +- toNodes: + - node1 + method: cliCommand + methodArgs: + - "bash" # Change from bash to ash for alpine containers + - "-c" + - | + kubectl apply -f '{{CTRL_FILE:./files/mydeployment.yaml}}' + + replyMethod: none + ACKTimeout: 0 +``` + +Create a new file in the `/files` folder named **mydeployment.yaml**. + +Commit the changes to the repo, and the deployment should be executed if you have a kubernetes instance running on **node1**. \ No newline at end of file diff --git a/doc/src/user_guide_install_docker.md b/doc/src/user_guide_install_docker.md index 6df5abf..16217b6 100644 --- a/doc/src/user_guide_install_docker.md +++ b/doc/src/user_guide_install_docker.md @@ -27,6 +27,7 @@ create a .env file cat << EOF > .env NODE_NAME="node1" BROKER_ADDRESS="127.0.0,1:4444" +NKEY_SEED= ENABLE_DEBUG=1 START_PUB_HELLO=60 IS_CENTRAL_ERROR_LOGGER=0