If you'd like to build and install your own instance of this project, you've come to the right page.
Back to the main page.
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 | -> .envThe port your web-server will be accessible when started later on (for example: 8080).This variable will be written to a newly generated .env file that will reside in the root-directory of the node web-server.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. 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.
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.