pages/README.md

# abstractnonsense/pages

These are scripts that we use on [git.abstractnonsense.se][git]
to have deployment to a [GitLab pages](gl-pages)-like environment.

They are meant to be used in conjunction with [actions/pages][action-pages]
to deploy to [pages.abstractnonsen.se][pages],
but could be set up for any other domain.

##  Requirements

You need
- a webserver with webroot
- write-access to the webroot by some user
- the ability to add ssh-keys to that user

## Setup
### initial setup
We recommend a system-user that is solely used for the pages
deployment. We will call it `pages` for the rest of this file.
Create it with
```
sudo adduser --system --shell /bin/bash --gecos 'Pages deployment' --group --disabled-password --no-create-home pages
```
Copy `deploy.sh` to `/home/pages/deploy.sh` (or some other place where you want to store it).
Edit the configuration variables in the file to your liking.
Here, you have to ensure that the `pages` user has write access to `WEB_ROOT` and `STORAGE_ROOT`.
Also make sure that `STORAGE_ROOT` has permissions so that other users cannot read it
with `sudo chmod 600 <STORAGE_ROOT>`.

### Settting up a new repository

For each new repository, you want to do the following:
Run `setup-key.sh <owner> <repository>` to generate a ssh keypair and set up the `pages` user to accept this.
Here, `<owner>` and `<repository>` can be anything, it will be the path relative to the webroot where this ssh key
will be able to deploy to, but this would be the recommended pattern for git instances.

In your repository, add the displayed ssh key as a secret (Settings -> Actions -> Secrets, note that Actions need to be enabled, see Settings -> Repository -> Advanced Settings)
named `PAGES_SSH_KEY`.
Now you should be fine to use the action as described in [actions/pages][action-pages].

[git]: https://git.abstractnonsen.se
[gl-pages]: https://docs.gitlab.com/ee/user/project/pages/
[action-pages]: https://git.abstractnonsen.se/actions/pages
[pages]: https://pages.abstractnonsen.se