fix(docs): first changes (#32228)
**Description** <!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. --> ⚒️ Fixes # <!--(issue)--> **⚙️ Type of change** - [ ] ⚙️ Feature/App addition - [ ] 🪛 Bugfix - [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] 🔃 Refactor of current code - [x] 📜 Documentation Changes **🧪 How Has This Been Tested?** <!-- Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration --> **📃 Notes:** <!-- Please enter any other relevant information here --> **✔️ Checklist:** - [ ] ⚖️ My code follows the style guidelines of this project - [ ] 👀 I have performed a self-review of my own code - [ ] #️⃣ I have commented my code, particularly in hard-to-understand areas - [ ] 📄 I have made changes to the documentation - [ ] 🧪 I have added tests to this description that prove my fix is effective or that my feature works - [ ] ⬆️ I increased versions for any altered app according to semantic versioning - [ ] I made sure the title starts with `feat(chart-name):`, `fix(chart-name):`, `chore(chart-name):`, `docs(chart-name):` or `fix(docs):` **➕ App addition** If this PR is an app addition please make sure you have done the following. - [ ] 🖼️ I have added an icon in the Chart's root directory called `icon.png` --- _Please don't blindly check all the boxes. Read them and only check those that apply. Those checkboxes are there for the reviewer to see what is this all about and the status of this PR with a quick glance._ --------- Signed-off-by: Alfred Göppel <43101280+alfi0812@users.noreply.github.com>
This commit is contained in:
Alfred Göppel
@@ -2,16 +2,17 @@
|
||||
title: Chart Structure
|
||||
---
|
||||
|
||||
This is a general synopsis about the structure of Helm Chart, it does not directly reflect TrueCharts specific settings.
|
||||
This is a general synopsis about the structure of Truecharts Helm Charts.
|
||||
|
||||
The following files are generally considered to be a "normal" Helm chart:
|
||||
|
||||
```text
|
||||
charts/<train>/<chart name>/
|
||||
charts/ # Directory containing dependency charts
|
||||
Chart.yaml # Required Helm chart information file
|
||||
README.md # Optional: Helm Readme file (will be rendered in TrueNAS SCALE UI as well)
|
||||
README.md # Optional: Helm Readme file (autogenerated)
|
||||
templates/ # A directory of templates that, when combined with values.yml will generate K8s YAML
|
||||
docs/ # Optional: A directory for any chart specific documentation
|
||||
ci/ # Optional: A directory for any ci-specific values for testing
|
||||
values.yaml # The default configuration values for this chart
|
||||
```
|
||||
|
||||
|
||||
@@ -12,13 +12,12 @@ apiVersion: The chart API version (required)
|
||||
kubeVersion: A SemVer range of compatible Kubernetes versions (optional)
|
||||
name: The name of the chart (required)
|
||||
version: A SemVer 2 version (required)
|
||||
upstream_version: A SemVer 2 version, as used by an upstream Helm Chart source (optional)
|
||||
appVersion: The version of the app that this contains (optional). Needn't be SemVer. Quotes recommended.
|
||||
description: A single-sentence description of this project (optional)
|
||||
type: The type of the chart (optional)
|
||||
deprecated: Whether this chart is deprecated (optional, boolean)
|
||||
home: The URL of this projects home page (optional)
|
||||
icon: A URL to an SVG or PNG image to be used as an icon (optional).
|
||||
icon: A URL to an SVG or PNG image to be used as an icon.
|
||||
keywords:
|
||||
- A list of keywords about this project (optional)
|
||||
sources:
|
||||
|
||||
@@ -36,8 +36,6 @@ You only need to do this once, as the fork can be re-used for all changes you wi
|
||||
To create a fork, navigate to the [truecharts/charts repository](https://github.com/truecharts/charts/fork) and press the
|
||||
Fork button in the upper-right corner.
|
||||
|
||||
|
||||
|
||||
On the following page, leave all of the default settings and click **Create Fork**. After a moment, you will presented with the main page of your fork,
|
||||
which is where you will first enact any changes that you wish to be added to the original repository.
|
||||
|
||||
@@ -47,48 +45,13 @@ repository is referred to as the _downstream repository_ or _downstream_.
|
||||
### The Git Workspace
|
||||
|
||||
The traditional way to use Git is to install a copy of it on your system and work with it locally; however,
|
||||
in order to keep things simple and convenient we are going to use Codespaces, a feature of GitHub that
|
||||
allows you to work on the repository with a variety of editors directly from your browser.
|
||||
in order to keep things simple and convenient we are going to use Visual Studio Code with the Github Integration.
|
||||
You can still use a traditional copy of Git if you'd like, and it's recommended to do so long term,
|
||||
but for now this guide will assume you're using Codespaces.
|
||||
but for now this guide will assume you're using Visual Studio Code.
|
||||
|
||||
1. Click the green **Code** button on your fork's page
|
||||
2. Switch to the **Codespaces** tab
|
||||
3. Click the **Create Codespace on master** button
|
||||
4. Wait until the codespace has been created (this can take some time due to the size of the repository)
|
||||
### Git
|
||||
|
||||
Just like with the fork itself, you only need to make a codespace once.
|
||||
|
||||
Once the codespace has fully loaded, you should close the default tabs present within the editor and the notifications in the
|
||||
lower right corner as none of them are relevant for work we will be doing.
|
||||
|
||||
Afterwards, it should look something like this:
|
||||
|
||||
|
||||
|
||||
While editing the repository, you may get more notifications in the lower right about features potentially not working due to missing components,
|
||||
as Codespaces tries to automatically detect which components may be useful to you depending on what files you open. These can simply be ignored and closed.
|
||||
|
||||
### Git Preface
|
||||
|
||||
Git can be interacted with with via the editor's UI, but we're going to use git entirely through its CLI via the terminal.
|
||||
Believe it or not this can sometimes be simpler. Also, it's universal as use of Git in this fashion is always the same regardless
|
||||
of your platform and environment, whereas every editor integrates git differently.
|
||||
|
||||
All Git commands begin with the word `git`
|
||||
|
||||
:::note
|
||||
|
||||
You can add the `--help` switch after any git command in order to view further information about said command.
|
||||
|
||||
```bash
|
||||
git commit --help
|
||||
```
|
||||
|
||||
Be aware that the official Git manual is highly detailed and technical. If you're stuck on a particular part, it may be easier to get help elsewhere.
|
||||
As always Google is your friend.
|
||||
|
||||
:::
|
||||
VS Code has great documentation and allows you to manage everything you need through their UI.
|
||||
|
||||
### Create a Topic Branch
|
||||
|
||||
@@ -98,19 +61,12 @@ a topic branch, which is just what it sounds like: A branch dedicated to a speci
|
||||
|
||||
**For TrueCharts specifically you should always create your topic branch off of the master branch.** Your workspace will be on the `master` branch by
|
||||
default, so you don't need to worry about this at first, but it's important to remember this when re-using a codespace for future changes. To get back
|
||||
to the master branch at any time use the `checkout` command like so:
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
```
|
||||
to the master branch you can use the bottom left section of VS Code
|
||||
|
||||
As for the topic branch to be created, this guide will pretend to add Installation Notes to the librespeed chart, so we will use the branch name
|
||||
`librespeed_inst_notes`. Try to keep branch names fairly terse, and of course use one that's appropriate for the change you're actually making.
|
||||
To create this branch and switch to it simultaneously:
|
||||
|
||||
```bash
|
||||
git checkout -b librespeed_inst_notes
|
||||
```
|
||||
Click on the current branch used and select "create new branch"
|
||||
|
||||
At this point, you can make the actual changes desired.
|
||||
|
||||
@@ -182,34 +138,9 @@ A good guideline for this is the concept of [atomic commits](https://dev.to/samu
|
||||
|
||||
For this particular example, we are only changing one file, and in a way that is entirely self-related (notes for installation) so one commit is fine.
|
||||
|
||||
#### Staging Files
|
||||
|
||||
Before a commit can be created, the files that are to be a part of that commit must be staged, which can more-or-less be thought of as just marking
|
||||
which files will be in the commit.
|
||||
|
||||
```bash
|
||||
git add --all
|
||||
```
|
||||
|
||||
This will stage **all** the files within the repository that you've modified, which in this case is fine since we've only changed one file.
|
||||
Just know that if you've changed multiple files but don't want all of them in the commit you will need to explicitly write out the paths
|
||||
to the files you want to stage after `git add` instead of using `--all`.
|
||||
|
||||
You can ask for a status check to ensure the appropriate file has been staged after the fact:
|
||||
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
#### Making the commit
|
||||
|
||||
Now its time to commit to your changes (get it?). Simply do the following:
|
||||
|
||||
```bash
|
||||
git commit
|
||||
```
|
||||
|
||||
This will open a new text file in the editor where you will need to write a commit message...
|
||||
Under Source Control of VSCode you can commit your changes with a meaningfull commit message
|
||||
|
||||
#### Commit message
|
||||
|
||||
@@ -229,33 +160,19 @@ A commit message should be 72 characters wide or less. In other words, use a lin
|
||||
The summary should be 72 characters or less **period**.
|
||||
|
||||
:::
|
||||
|
||||
The body of the message follows the summary and must be separated by two line-breaks (e.g. so that there's an empty line between them).
|
||||
Details about the commit are to be contained in the body, often with a rationale behind the changes. The _why_ is just as important as the _what_;
|
||||
however, for very simple and largely self-explanatory commits like our example, a body isn't even necessary.
|
||||
|
||||
A final note is that generally you want to write commit messages in the [present tense and imperative mood](https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/SubmittingPatches?h=v2.36.1#n181)
|
||||
(i.e. somewhat like you're stating a command). For this example, the following is a good commit message:
|
||||
|
||||
Add installation notes to librespeed
|
||||
|
||||
For future reference, when making commits with simple messages like this you can save time by entering them directly on the command line like so:
|
||||
|
||||
```bash
|
||||
git commit -m "Message here"
|
||||
```
|
||||
|
||||
Once finished, save the file and then close its tab in the editor, this will complete the commit with the supplied message.
|
||||
|
||||
### Push the commit to the remote repository
|
||||
|
||||
This step requires a brief explanation of how Git repositories are typical managed in this context. In this situation there are actually three copies
|
||||
of the same repository. The terms for these can vary, but generally there is:
|
||||
|
||||
1. (local) The copy of the repository on your local system where you are actually working. Here, this is slightly confusing since you're using
|
||||
2. GitHub Workspaces which is in the cloud, but it still must be thought of as a "local" system.
|
||||
3. (origin/remote) The copy of your fork on GitHub itself. This is what you can see/browse when you go to your fork's URL in your browser.
|
||||
4. (upstream) This is the original TrueCharts repository from which you initially created a fork.
|
||||
2. (origin/remote) The copy of your fork on GitHub itself. This is what you can see/browse when you go to your fork's URL in your browser.
|
||||
3. (upstream) This is the original TrueCharts repository from which you initially created a fork.
|
||||
|
||||
:::note
|
||||
|
||||
@@ -271,14 +188,10 @@ This is done with the `push` command, which updates the version of your current
|
||||
in your local copy; however, in this case since the `librespeed_inst_notes` branch also currently only exists in our local repository we need to create
|
||||
the branch on the origin as well. Git provides a shortcut for pushing changes on a new branch to the remote repo in one step:
|
||||
|
||||
```bash
|
||||
git push --set-upstream origin librespeed_inst_notes
|
||||
```
|
||||
Click the push button in the Source Control Page.
|
||||
|
||||
You will now notice that your fork on GitHub also has the new branch, along with the commit we just made.
|
||||
|
||||
The Workspaces session is no longer needed and can be closed.
|
||||
|
||||
### Make a Pull Request
|
||||
|
||||
The final step to integrating your changes is to submit a PR (pull request) to the upstream repository. This is a formal request for the upstream
|
||||
@@ -288,8 +201,6 @@ To do so, navigate to the main page of the upstream repository on [GitHub](https
|
||||
since you pushed to your remote, you will notice a convenient button for creating a PR based on your topic branch presented to you by GitHub.
|
||||
But just in-case it's not there, this guide will ignore it and demonstrate the slightly longer way.
|
||||
|
||||
|
||||
|
||||
1. Click the **Pull requests** tab at the top left of the repo.
|
||||
2. Click the green **New pull request** button near the top left of the next page
|
||||
3. Click the blue text that says **compare across forks** under the "Compare changes" heading
|
||||
@@ -310,42 +221,14 @@ work is done and you can delete the topic branch on your fork if you wish.
|
||||
|
||||
#### Making changes
|
||||
|
||||
If the project maintainers request changes, you must re-open your GitHub workspace (which will have a randomly generated goofy name) to make the changes.
|
||||
As a general rule of thumb in git, **do not alter existing commits and instead make alterations by creating new ones**; _however_, creating PRs via a
|
||||
topic branch is one of the exceptions in which not only is it appropriate to modify previous commits, but often preferred.
|
||||
If the project maintainers request changes, you must re-open your VS Code to make the changes.
|
||||
As a general rule of thumb in git, **do not alter existing commits and instead make alterations by creating new ones**;
|
||||
|
||||
Once back in your workspace, make the required changes to your documentation file and then stage them as before.
|
||||
|
||||
```bash
|
||||
git add --all
|
||||
```
|
||||
|
||||
This time however, instead of making a new commit we are going to update the one we made before.
|
||||
|
||||
```bash
|
||||
git commit --amend --no-edit
|
||||
```
|
||||
|
||||
`--no-edit` tells git to keep the previous commit message as is. If you need to edit the message too, do not include that switch.
|
||||
|
||||
Finally, push the changes to the origin repo while also acknowledging to git that you are overwriting past changes
|
||||
|
||||
```bash
|
||||
git push --force-with-lease
|
||||
```
|
||||
|
||||
Forcing a push like this is known as "rewriting history" and is not something that should be done lightly, but this is one of the cases where it is appropriate.
|
||||
Once back in your workspace, make the required changes to your documentation file and then commit & push them as before.
|
||||
|
||||
Once your origin repository is updated the changes will also automatically be reflected within the pull request. Repeat this process as needed until
|
||||
the PR satisfies project maintainers.
|
||||
|
||||
:::note
|
||||
|
||||
Revising more than one commit is more complicated and out of the scope of this guide. Remember, you can always play things safe by just creating new
|
||||
commits with your edits instead of amending past ones.
|
||||
|
||||
:::
|
||||
|
||||
#### Future changes
|
||||
|
||||
When preparing to submit a subsequent PR there are two important things to remember.
|
||||
@@ -356,23 +239,6 @@ of TrueCharts, as by default your fork will remain in whichever state you last l
|
||||
To do this, navigate to your fork's homepage on GitHub. While being sure that the branch drop-down is set to **master** select the **Sync fork** option
|
||||
and hit the green **Update branch** button.
|
||||
|
||||
|
||||
|
||||
Second, when returning to your codespace you'll notice that it's still on the topic branch you created before (if you haven't deleted it yet). You can
|
||||
either create a new codespace on the master branch, or open that codespace and return to the master branch by using the command shared previously:
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
```
|
||||
|
||||
Second, when returning to your VSCode you'll notice that it's still on the topic branch you created before (if you haven't deleted it yet).
|
||||
You can use the section in the bottom right to switch back to the master branch.
|
||||
From here you can start work on your next PR.
|
||||
|
||||
## TODO
|
||||
|
||||
---
|
||||
|
||||
- Include tips for handling rebasing to account for upstream changes by maintainers
|
||||
- Include tips for handling merge-conflicts
|
||||
- Add more pictures
|
||||
- Note how to add images to documentation
|
||||
- Note how to add warning/note blocks
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Useful Commands Cheatsheet
|
||||
---
|
||||
|
||||
These are some commands that are nice to keep track of:
|
||||
|
||||
**give execute permissions to all sh files:**
|
||||
`find . -name '*.sh' | xargs git update-index --chmod=+x`
|
||||
|
||||
**list all used repositories in the catalog:**
|
||||
`find . -name 'values.yaml' | xargs cat | grep "repository" | grep -v "{" | awk -F":" '{ print $2 }' | grep -v '^$' | sort --unique`
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: Ingress
|
||||
---
|
||||
|
||||
Ingress is what we call "Reverse Proxy" in the UI and in the user side of the documentation. Please be aware that those refer to the same system. An Ingress is, simply put, just Kubernetes way of connecting outsides to Apps running in containers.
|
||||
|
||||
## Ingress Types
|
||||
|
||||
We currently support:
|
||||
|
||||
- HTTP via Ingres
|
||||
- HTTP via Traefik IngressRoute (HTTP-IR)
|
||||
- TCP via Traefik IngressRouteTCP
|
||||
- UDP via Traefik IngressRouteUDP
|
||||
|
||||
From questions.yaml and the UI, these can be changed with selecting another "Type". However: Under the hood IngressRoutes and Ingress are totally different beasts and have a separate creation process. Errors for Plain HTTP do NOT have to be present in HTTP-IR.
|
||||
|
||||
It's also important to note that TCP (and even more so: UDP) have less options available. The example configurations below contain a mostly complete overview of what is currently available and reasonable.
|
||||
|
||||
### Ingress and Services
|
||||
|
||||
It's important to know what Ingress does, before you start creating ingresses in questions.yaml. Ingresses send outside Traffic, to a kubernetes Service, which in turn forwards traffic to the actual containers.
|
||||
|
||||
This means that every container needs to know how to reach their Service. If they do not, things go wrong.
|
||||
|
||||
To ensure this, it's advised to keep the names of your Ingresses the same as the names of your services. We made sure the ingress would automatically detect (and connect to) the main port of a Service with the same name.
|
||||
|
||||
However: In case you need to do this differently, need to connect to additionalServices and/or need to connect to a secondary port, you can manually set both the serviceName and servicePort in questions.yaml. We advice however, to only do so if absolutely necessary!
|
||||
|
||||
### The Main Ingress
|
||||
|
||||
The main Ingress and Main service take an important role in our standardization. Where the main Service is used for healthchecks.
|
||||
|
||||
However: As the maintainers expect new features to be connecting to the main service and main ingress, it will cause problems if you decide to bypass/ignore these.
|
||||
|
||||
### Standards/Examples
|
||||
|
||||
We try to maintain as much of a standardized questions.yaml format as possible, to ensure (bulk) editing stays as easy as possible.
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Services
|
||||
---
|
||||
|
||||
Every App needs to be exposed to something, either an UI, API or other containers.However with Kubernetes we don't directly connect to the containers running the App, because those might be on another node or there might be multiple "high available" containers for the App. Instead we use what is called `Services`. Services are simply put "Internal Load-Balancers", they also guaranteed to be reachable by (internal!) DNS name and (in some cases) prevent traffic from reaching your App when the healthcheck isn't finished yet (or is failing).
|
||||
|
||||
## Two kinds of services
|
||||
|
||||
### Main Service
|
||||
|
||||
Every App **must** have a `main` service, the primary connection for users or other apps, whether it's a webUI, an API, a database connection or something else. Keep in mind that every App is unique, some may have one service called `main`, while others may need multiple services with **distinct** names. Also, every App uses different ports, so make sure to alter accordingly.
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: Storage
|
||||
---
|
||||
|
||||
This article serves as a development extension to the storage article available [here](https://wiki.truecharts.org/general/storage/)
|
||||
|
||||
## Storage and Common-Chart
|
||||
|
||||
For all these storage solutions we require the common-chart to be added to the App.
|
||||
The Common-Chart handles both the connection/addition of storage to the container and spinning up special k8s jobs to fix the permissions if requested for the Custom storage.
|
||||
|
||||
### Unlimited Custom Storage Mounts
|
||||
|
||||
We support presenting the user with a "Do it yourself" style list, in which the user can add unlimited paths on the host system to mount.
|
||||
It should always be included in any App, to give users the option to customize things however they like.
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
title: Values.yaml
|
||||
---
|
||||
|
||||
Values.yaml files generally always contain configuration setting for Helm charts, TrueCharts is no different.
|
||||
However, we have multiple different values.yaml files, with different goals. Because TrueNAS SCALE just works slightly differently from standard Helm Charts
|
||||
|
||||
## The Files
|
||||
|
||||
### values.yaml
|
||||
|
||||
This file contains the default config when running the App using stock helm (not SCALE). It also gets used for the testing suite.
|
||||
|
||||
A minimal example values.yaml would be:
|
||||
|
||||
```yaml
|
||||
##
|
||||
# This file contains Values.yaml content that gets added to the output of questions.yaml
|
||||
# It's ONLY meant for content that the user is NOT expected to change.
|
||||
# Example: Everything under "image" is not included in questions.yaml but is included here.
|
||||
##
|
||||
|
||||
image:
|
||||
repository: docker.io/jacobalberty/unifi
|
||||
tag: 6.0.45
|
||||
pullPolicy: IfNotPresent
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user