Skip to content

Commit

Permalink
doc update
Browse files Browse the repository at this point in the history
  • Loading branch information
@guFalcon
guFalcon committed Jan 10, 2025
1 parent c9265b3 commit cf5d9d5
Show file tree
Hide file tree
Showing 7 changed files with 353 additions and 332 deletions.
345 changes: 13 additions & 332 deletions README.md
View file

Large diffs are not rendered by default.

43 changes: 43 additions & 0 deletions docs-building.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Building
If you'd like to build and install your own instance of this project, you've come to the right page.

[back](README.md) to the main page.
## How To Build / Update
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.
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).

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.
So if you'd like to use the privacy and permissions features of this project, you better host this image somewhere private.

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).

| NAME | DESCRIPTION |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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). |
| 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`. |
| PLANTUML_URL | Defaults to `https://plantuml.unterrainer.info/plantuml` |
| DEPLOY_DIR | The absolute path to the installation-directory on your target machine (server). Example would be: `/app/deploy/safe-learn`. |
| 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`. |
| DEPLOY_SERVER | The host-address of your server (as accessible from a Github runner). |
| DEPLOY_SSH_PORT | The port for the SSH connection to your server. |
| DEPLOY_SSH_PRIVATE_KEY | The private key for SSH authentication. |
| DEPLOY_SSH_USER | The user for SSH authentication (local user). |
| DOCKER_HUB_PASSWORD | An access-token of your docker-hub account. |
| DOCKER_HUB_USER | The user of your docker-hub account. |
| 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`) |
| KEYCLOAK_FILE | The copy-pasted contents of the file you get when you enter your Keycloak-realm as admin -> Client -> Installation -> Keycloak JSON File. |
| 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. |
| 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. |
| 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. |
| VPN_PASSWORD | The password of your VPN connection. |
| VPN_SERVER | The server to call for opening your VPN connection. |
| VPN_USERNAME | The username of your VPN connection. |

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.
Upon entering any page you'll be prompted to login at the given Keycloak server in order to gain access.

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.
## Github Actions Settings
You'll have to enable write-access for actions by enabling these options:
![[Pasted image 20240409164504.png]]
`Project-Settings -> Actions -> General -> Workflow permissions -> Read and write permissions AND Allow GitHub Actions to create and approve pull requests`.
46 changes: 46 additions & 0 deletions docs-debugging.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# # Debugging
Here you can find help with debugging the project.

[back](README.md) to the main page.
## Debugging
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.
Just do the following:
* clone this repository
* open it in VSCode
* open a terminal window
* `npm install`
* `npm run start` (the contents of the start-script are located in the `package.json` file)
* Just press `F5` to start debugging, while the webserver is running in the background
You can use the built-in debugger now.

The following files are changed or omitted in the build-process:

| FILE | DESCRIPTION |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| .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. |
| 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. |
| 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. |
| app.js | -> 'Dockerfile'<br>Is the start-file for the NodeJS server and will be copied during the pipeline-run's Docker-Image generation. |
| all other files... | Will be ignored by the build-pipeline. |
### HttpYac (REST-Tests)
In order to get those working, you'll have to create a file `httpyac.config.js` with the following contents:
```bash
// Configuration file for HttpYac.
// A plugin for VSCode.
module.exports = {
  log: {
    supportAnsiColors: true
  },
  cookieJarEnabled: true,
  envDirName: 'env',
  environments: {
    $default: {
      url: 'http://localhost:8080',
      oidc: 'https://keycloak-server/auth/realms/test/protocol/openid-connect/token',
      userName: 'username',
      password: 'password'
    }
  }
}
```
Then you can run the REST-examples in the `http` directory.
16 changes: 16 additions & 0 deletions docs-keycloak.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
Here you find information about the keycloak-setup when you're trying to host it yourself.

[back](README.md) to the main page.
## Keycloak Setup
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).
You need the following user-attributes of type `string` with mapper to the token.
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.
The application uses the following endpoints of the Keycloak-API to do that:
- `GET {{keycloakUrl}}/realms/{{realm}}/account`
- `POST {{keycloakUrl}}/realms/{{realm}}/account`
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.

| ATTRIBUTE-NAME | TYPE | DESCRIPTION |
| ------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| 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. |
| Client -> Client Scopes -> ...-dedicated -> Add Mapper (User Attribute)<br>`lastVisitedUrl` | string | Holds the last-visited page of the current user. |
74 changes: 74 additions & 0 deletions docs-obsidian.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Obsidian Extensions
Here you can find the technical intricacies of the Obsidian-specific language extension.

[back](README.md) to the main page.
## Globally Unique File Names
Obsidian uses quick-links like so:
```markdown
# The next line will insert a link to a file.
[[md-file-name-without-extension]]

# The next line will insert an image.
![[image-file-name-with-extension]]
```
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.
Same goes for images and other assets.
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.

So plan your file-names carefully.
You'll be rewarded with a much faster and smoother editing-experience.
## Callouts
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).
Those look great, especially when dealing with long text-flow or when interspersing text with info-points or homework-reminders.

Examples:
```markdown
# A note.
> [!note]
> content
```
![](md/assets/Pasted%20image%2020240315082827.png)

```markdown
# A Warning with 'BOO!' in the heading, instead of the default 'Warning'.
>[!warning] BOO!
>content
```
![](md/assets/Pasted%20image%2020240315082849.png)

```markdown
# A collapsable callout
>[!tip]-
>content
```
![](md/assets/Pasted%20image%2020240315082907.png)

```markdown
# A collapsable callout with 'some long text' as heading.
>[!quote]- some long text
>content
```
![](md/assets/Pasted%20image%2020240315083209.png)

You get the idea.
You can see all the variations [here](https://help.obsidian.md/Editing+and+formatting/Callouts).

They all work with one exception:
![](md/assets/Pasted%20image%2020240315082944.png)
## Image Sizing
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.

To display images at a special size, you have the following options.
Those work on normal image-links, like the standard DM ones and the shortcut-links `Obsidian` provides.

```markdown
# Display in 200x200 pixels (x + 'x' + y)
![some alt-text|200x200](assets/my-img.png)
# And as short-link
![[my-img.png|200x200]]

# Display in 200 pixels widths, sized proportionally
![some alt-text|120](assets/my-img.png)
# And as short-link
![[my-img.png|120]]
```
Loading

0 comments on commit cf5d9d5

Please sign in to comment.