Skip to content

Commit cf5d9d5

Browse files
guFalconguFalcon
committed
doc update
1 parent c9265b3 commit cf5d9d5

File tree

7 files changed

+353
-332
lines changed

7 files changed

+353
-332
lines changed

‎README.md

Lines changed: 13 additions & 332 deletions
Large diffs are not rendered by default.

‎docs-building.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Building
2+
If you'd like to build and install your own instance of this project, you've come to the right page.
3+
4+
[back](README.md) to the main page.
5+
## How To Build / Update
6+
The repository derives from https://github.com/htl-leonding-college/asciidoctor-docker-template and adds functionality to publish the output to a web-server of your liking using DockerHub.
7+
It hides (server-side) all pages behind a OIDC token redirecting to an authentication server of your liking (in the default-case it's client on a Keycloak instance linked to our school's AD service, so we never have to maintain the users because the school does this for us).
8+
9+
You will need a web-server of your own and some way of hosting a private docker-image, since your material won't be protected from students in a public one.
10+
So if you'd like to use the privacy and permissions features of this project, you better host this image somewhere private.
11+
12+
To build, there is a Github action in this repository, but in order to configure it, you'll need several secrets available for the build (add them to your Company/Organisation/clone of this repo).
13+
14+
| NAME | DESCRIPTION |
15+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16+
| START_PAGE | Relative local path to the desired start-page, starting with the app.js directory, which is the root for the webserver (defaults to `/index.html`, which will be the ASCIIDoc-start-page generated by jekyl). So, for example, the correct way to start with index.md located in your `md` sub-directory would be setting this variable to `/md/index.md` (it will run through the markdown-processor alright). |
17+
| SERVER_URL | This is the URL your server will be available at later, after deploying. Examples are `https://htl.unterrainer.info` or the default `http://localhost:8080`. |
18+
| PLANTUML_URL | Defaults to `https://plantuml.unterrainer.info/plantuml` |
19+
| DEPLOY_DIR | The absolute path to the installation-directory on your target machine (server). Example would be: `/app/deploy/safe-learn`. |
20+
| DATA_DIR | The absolute path to the data-directory on your target machine (server). That's where all the docker-volumes will be mapped to, if any so that you'll be safe if you backup exactly this directory. Example would be: `/app/data/safe-learn`. |
21+
| DEPLOY_SERVER | The host-address of your server (as accessible from a Github runner). |
22+
| DEPLOY_SSH_PORT | The port for the SSH connection to your server. |
23+
| DEPLOY_SSH_PRIVATE_KEY | The private key for SSH authentication. |
24+
| DEPLOY_SSH_USER | The user for SSH authentication (local user). |
25+
| DOCKER_HUB_PASSWORD | An access-token of your docker-hub account. |
26+
| DOCKER_HUB_USER | The user of your docker-hub account. |
27+
| DOCKER_IMAGE_NAME | The image name that should be built and deployed (example: `safe-learn` with DOCKER_HUB_USER `gufalcon` would result in pulling the image `gufalcon/safe-learn:latest`) |
28+
| KEYCLOAK_FILE | The copy-pasted contents of the file you get when you enter your Keycloak-realm as admin -> Client -> Installation -> Keycloak JSON File. |
29+
| PORT | -> `.env`<br>The port your web-server will be accessible when started later on (for example: `8080`).<br>This variable will be written to a newly generated `.env` file that will reside in the root-directory of the node web-server.<br>So that port is INSIDE this web-servers' docker-image that is created. |
30+
| WEBSERVER_PORT | This is the EXTERNAL port of the web-server that is created.<br>This port must be unique and accessible on the deployment-machine. |
31+
| VPN_OVPN_FILE | The OVPN file of your Open VPN configuration. This is used to reach the deployment-server (target host) to start conversation via SSH. |
32+
| VPN_PASSWORD | The password of your VPN connection. |
33+
| VPN_SERVER | The server to call for opening your VPN connection. |
34+
| VPN_USERNAME | The username of your VPN connection. |
35+
36+
After starting the build-pipeline on Github for the first time after inserting all these values, you should have a NodeJS server deployed and up-and-running on your target machine, accessible via the PORT you entered as a secret.
37+
Upon entering any page you'll be prompted to login at the given Keycloak server in order to gain access.
38+
39+
If your repository is private, which makes sense, Github will force you to either pay for Github Enterprise, or to have your own, self-hosted Github Runner. Because this repository however is public, the build-action-script refers to the runner as `runs-on: ubuntu-latest`. So in order to use your private self-hosted-runners you'll have to label them `ubuntu-latest` so Github will take care of that. Your runners will have slightly higher priority than the public ones.
40+
## Github Actions Settings
41+
You'll have to enable write-access for actions by enabling these options:
42+
![[Pasted image 20240409164504.png]]
43+
`Project-Settings -> Actions -> General -> Workflow permissions -> Read and write permissions AND Allow GitHub Actions to create and approve pull requests`.

‎docs-debugging.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# # Debugging
2+
Here you can find help with debugging the project.
3+
4+
[back](README.md) to the main page.
5+
## Debugging
6+
To test the portions of the web-site that isn't directly connected to the gh-pages generation and Asciidoc conversion, you may want to start it using VSCode.
7+
Just do the following:
8+
* clone this repository
9+
* open it in VSCode
10+
* open a terminal window
11+
* `npm install`
12+
* `npm run start` (the contents of the start-script are located in the `package.json` file)
13+
* Just press `F5` to start debugging, while the webserver is running in the background
14+
You can use the built-in debugger now.
15+
16+
The following files are changed or omitted in the build-process:
17+
18+
| FILE | DESCRIPTION |
19+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
20+
| .env | -> `pipeline`<br>Will be re-generated from scratch during the pipeline-run using Github secrets.<br>Code is located in this repository in the `yml` file of the action. |
21+
| keycloak.json | -> `pipeline`<br>Will be generated from scratch during the pipeline-run using Github secrets.<br>So you're free to place a debugging-file of your own in here. The one that is present connects you to a test-server and will most likely not work with your fork. |
22+
| package.json<br>package-lock.json | -> 'Dockerfile'<br>These files will be copied during the pipeline-run's Docker-Image generation and used to setup the web-server in the Docker container by running `npm install` afterwards. |
23+
| app.js | -> 'Dockerfile'<br>Is the start-file for the NodeJS server and will be copied during the pipeline-run's Docker-Image generation. |
24+
| all other files... | Will be ignored by the build-pipeline. |
25+
### HttpYac (REST-Tests)
26+
In order to get those working, you'll have to create a file `httpyac.config.js` with the following contents:
27+
```bash
28+
// Configuration file for HttpYac.
29+
// A plugin for VSCode.
30+
module.exports = {
31+
  log: {
32+
    supportAnsiColors: true
33+
  },
34+
  cookieJarEnabled: true,
35+
  envDirName: 'env',
36+
  environments: {
37+
    $default: {
38+
      url: 'http://localhost:8080',
39+
      oidc: 'https://keycloak-server/auth/realms/test/protocol/openid-connect/token',
40+
      userName: 'username',
41+
      password: 'password'
42+
    }
43+
  }
44+
}
45+
```
46+
Then you can run the REST-examples in the `http` directory.

‎docs-keycloak.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Here you find information about the keycloak-setup when you're trying to host it yourself.
2+
3+
[back](README.md) to the main page.
4+
## Keycloak Setup
5+
In order for this setup to work correctly, you'll have to have a Keycloak-client (private with secret) and standard-authorization-flow enabled (should be enabled anyway).
6+
You need the following user-attributes of type `string` with mapper to the token.
7+
You also need to add the user-attributes to the user-profile first (`Realm settings` -> `User profile (Attribute group = none, not user-metadata)`) in order to allow for the addition of data to your users. Be sure to set those to `allow edit and view for User and Admin` so that the application is able to change the values.
8+
The application uses the following endpoints of the Keycloak-API to do that:
9+
- `GET {{keycloakUrl}}/realms/{{realm}}/account`
10+
- `POST {{keycloakUrl}}/realms/{{realm}}/account`
11+
The user-metadata field `LDAP_ENTRY_DN` will be automatically present because of the LDAP mapper in your Keycloak instance. It will be readable from the `access-token`. So there are no additional setup-steps requried.
12+
13+
| ATTRIBUTE-NAME | TYPE | DESCRIPTION |
14+
| ------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
15+
| Client -> Client Scopes -> ...-dedicated -> Add Mapper (User Attribute)<br>`config` | string | Holds several preference-values like dark-mode or not or the preferred font, fontsize or line-height. |
16+
| Client -> Client Scopes -> ...-dedicated -> Add Mapper (User Attribute)<br>`lastVisitedUrl` | string | Holds the last-visited page of the current user. |

‎docs-obsidian.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Obsidian Extensions
2+
Here you can find the technical intricacies of the Obsidian-specific language extension.
3+
4+
[back](README.md) to the main page.
5+
## Globally Unique File Names
6+
Obsidian uses quick-links like so:
7+
```markdown
8+
# The next line will insert a link to a file.
9+
[[md-file-name-without-extension]]
10+
11+
# The next line will insert an image.
12+
![[image-file-name-with-extension]]
13+
```
14+
In order to be able to do that, you are not allowed to have two files with the exact same file-name within a vault. Even if they are located in different directories.
15+
Same goes for images and other assets.
16+
If you have two files, for example, named `test`, then you'll have to add the complete path in links to any of the two `test` files.
17+
18+
So plan your file-names carefully.
19+
You'll be rewarded with a much faster and smoother editing-experience.
20+
## Callouts
21+
Contrary to GitHub or standard MD, Obsidian supports [callouts](https://help.obsidian.md/Editing+and+formatting/Callouts), which are basically colorfully rendered boxes with headings and content (cards, one might say).
22+
Those look great, especially when dealing with long text-flow or when interspersing text with info-points or homework-reminders.
23+
24+
Examples:
25+
```markdown
26+
# A note.
27+
> [!note]
28+
> content
29+
```
30+
![](md/assets/Pasted%20image%2020240315082827.png)
31+
32+
```markdown
33+
# A Warning with 'BOO!' in the heading, instead of the default 'Warning'.
34+
>[!warning] BOO!
35+
>content
36+
```
37+
![](md/assets/Pasted%20image%2020240315082849.png)
38+
39+
```markdown
40+
# A collapsable callout
41+
>[!tip]-
42+
>content
43+
```
44+
![](md/assets/Pasted%20image%2020240315082907.png)
45+
46+
```markdown
47+
# A collapsable callout with 'some long text' as heading.
48+
>[!quote]- some long text
49+
>content
50+
```
51+
![](md/assets/Pasted%20image%2020240315083209.png)
52+
53+
You get the idea.
54+
You can see all the variations [here](https://help.obsidian.md/Editing+and+formatting/Callouts).
55+
56+
They all work with one exception:
57+
![](md/assets/Pasted%20image%2020240315082944.png)
58+
## Image Sizing
59+
The renderer will never touch the image's size, until it won't fit the display. If that occurs, it will just resize it proportionally to fit it.
60+
61+
To display images at a special size, you have the following options.
62+
Those work on normal image-links, like the standard DM ones and the shortcut-links `Obsidian` provides.
63+
64+
```markdown
65+
# Display in 200x200 pixels (x + 'x' + y)
66+
![some alt-text|200x200](assets/my-img.png)
67+
# And as short-link
68+
![[my-img.png|200x200]]
69+
70+
# Display in 200 pixels widths, sized proportionally
71+
![some alt-text|120](assets/my-img.png)
72+
# And as short-link
73+
![[my-img.png|120]]
74+
```

0 commit comments

Comments
 (0)