Content manager for sunet.se

This software is for managing the sunet.se site. It has to be installed in 2 different places: in the server that will host the site, and in the machine of the editor that will manage the site.

There are 2 git repositories involved in this. One is for the content that holds the markdown content as an obsidian vault, and the other is the present one, that has the code to build the html site from the markdown in the content repo and to serve it in a docker container.

Development is done in the staging branch, then merged to main.

Installation on the server machine.

The service is run as a docker container, so we need docker in the machine that will host the site.

The container runs an NGINX process, with 2 locations: the public location that will serve the static site, and a restricted location (protected with basic auth credentials) offering the /refresh-content endpoint, which when accessed will trigger fetching all the new content from the content repo and building it.

Clone the code repo and cd to the docker container:

$ git clone git@github.com:SUNET/sunet-se-code.git
$ cd sunet-se-code

Now we need to build the docker image:

$ docker build -t sunet-se:latest .

Then, to run a container, we need to provide a few environment variables.

Required variables:

• JIRA_PASSWORD The password for the Sunet JIRA API to pull the tickets for the arenden section. Obtained from the JIRA operators.
• REFRESH_PASSWORD The basic auth password for the /refresh-content endpoint. This is created anew here, and then set (as desccribed below) in the editor's environment.

Optional variables:

• SERVER_NAME The hostname of the service, e.g. staging.sunet.se. Default "sunet.se"
• GITHUB_CONTENT_REPO: Github repo with the sunet.se content. Default "git@github.com:SUNET/sunet-se-content.git"
• GIT_BRANCH: the git branch of the content repo that will be used to build the site. Default "staging".
• REFRESH_USERNAME The basic auth username for the /refresh-content endpoint. Default "editor"
• JIRA_BASEURL: Base URL for the JIRA API. Default "https://jira-test.sunet.se/rest/api/2"
• JIRA_USERNAME: Username for the JIRA API. Default "restsunetweb".
• JIRA_PROJECT: JIRA projecct from which the tickets will be pulled. Default "TIC".
• MAX_CLOSED_AGE: Only retrieve closed tickets that were closed less than this number of days ago. Default "30d".
• SSH_PRIVATE_KEY_LOCATION: location in the container of the ssh public key to pull the content repo from github Default "/root/.ssh/server_key"
• CERTNAME: Name of the TLS certificate and key, so NGINX will try to find them at /etc/ssl/certs/${CERTNAME}.crt and /etc/ssl/private/${CERTNAME}.key. Default: sunet.se

Also, since the sunet content repo is private at github, we need to mount the ssh keys on the container. We mount the directory rw since we will want to add github to known_hosts. So here we assume that ./ssh contains an ssh key that has permission to pull from the content repo.

Likewise for HTTPS we need to provide the TLS cert and private key, so here we assume that ./ssl contains those:

$ tree ssl
ssl
├── certs
│   └── sunet.se.crt
└── private
    └── sunet.se.key

3 directories, 2 files

So, a possible command to run the image:

$ docker run -d -p 443:443 --volume ./ssh:/root/.ssh:rw --volume ./ssl:/etc/ssl:ro --env JIRA_PASSWORD=secret1 --env REFRESH_PASSWORD=secret2 --name sunet sunet-se:latest

Finally, to retrieve JIRA issues to display them in the arenden secion of the site, set up a cron job in the host machine that executes the command:

docker exec sunet bash -c "/usr/local/bin/update_issues.sh"

Installation in the editor's machine.

The editor's machine needs to have git and obsidian installed.

Clone the content repo, and make sure that changes committed in the local clone can be pushed to github. The obsidian plugin in charge of pushing changes assumes that git push is already provided with credentials (e.g., via ssh).

$ git clone git@github.com:SUNET/sunet-se-content.git
$ cd sunet-se-content
$ git checkout staging

For development and testing purposes, it is possible to use a different git branch. This branch must exist already both locally and at github, so something like this should have been done:

$ git checkout -b test-dev
$ git push --set-upstream origin test-dev

Then the server docker container should be run with an env var --env GIT_BRANCH=test-dev.

Then clone the obsidian config repo within the content repo and initialize it:

$ git clone git@github.com:SUNET/sunet-se-obsidian.git .obsidian
$ cd .obsidian
$ make init

Open obsidian, and look for "open folder as vault" (from "open another vault"), and in the resulting dialog select the cloned content repo.

Go to the obsidian settings, and under "community plugins" click on "Sunet plugin". Here we have to enter the URL for the refresh-content endpoint of the staging server (e.g. https://staging.sunet.se/refresh-content), and the username and password that have been set in the staging server as REFRESH_USERNAME and REFRESH_PASSWORD.

To use a development git branch for the content, e.g. the test-dev branch we created above, add it in the settings, in "Staging Git Branch". The staging branch is the default. This branch should be provided to the staging server as GIT_BRANCH (see above).

After this, the editor should be all set to start working on the site.