webring/README.md

# Adding yourself to the webring

Add your information to `webring_data.json`.
The schema is as follows:

- **`id`**: a unique id for your entry.
  You will use this id when adding webring links on your own blog/page.
- **`title`**: the title you want to use on the webring directory.
- **`author`**: the name you want to use on the webring directory.
- **`url`**: the URL to redirect to whenever the webring needs to point a visitor to your entry.

Create a PR with your changes.

## Testing your entry

Run `deno task dev`, which should start a local web server.
You can then navigate to it to inspect how your entry will look on the webring's main page, as well as make sure the url it points to works fine.

# Using the webring on your blog/page

Somewhere in your blog/page (footer recommended), add the following links.
Remember to replace `<YOUR_ID_HERE>` with the unique id for your entry on the webring.

Note: it's ok for you to add these links to your page before your PR gets approved and merged.
The webring will redirect to random pages when given an unknown id.
Whenever your PR gets approved and merged, your id will be recognised and you'll officially be part of the webring.

- Previous entry: `https://akols.com/previous?id=<YOUR_ID_HERE>`
- Next entry: `https://akols.com/next?id=<YOUR_ID_HERE>`
- A link to the webring directory: `https://akols.com`

# Development setup

## Setting up VSCode (and flavours)

We're using [Deno](https://deno.com) in the webring functions, so if you want proper editor support, you'll need to install the [Deno extension](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno).
There's already a `.vscode` directory which should direct VSCode to enable the Deno extension for this project.

# Infrastructure

## Setting up SSH access

You'll need to trust the SSH certificate authority that generates SSH keys for Epesooj's hosts.
The CA's public key is in `./host_config/ssh_certs/host_ca.pub`.

This is the template for the SSH `known_hosts` entry:

```
@cert-authority <dns name or ip address> <CONTENTS OF host_ca.pub>
```

For example:

```
@cert-authority code.akols.com ssh-ed25519 AAAA...
```

## Signing a user's public SSH key to give them host access

Run `just sign_user_key <username> <user_pub_key_path>`.
This will by default give them `root` access.
Check the definition of this `just` command to see how to give them access to different user(s).

Once this is done, give them the signed public key (it'll be a file in the same directory as `<user_pub_key_path>` with the `-cert.pub` suffix) and tell them to add the `CertificateFile` option to their SSH config to make sure it'll also present the signed public key.
For example:

```
Host epesooj
  User root
  HostName code.akols.com
  IdentityFile ~/.ssh/epesooj_personal.pub
  CertificateFile ~/.ssh/epesooj_personal-cert.pub
  IdentitiesOnly yes
```

## Nixifying a new host

If you have a bunch of SSH keys in your SSH agent and get errors when trying to SSH into a fresh host, you may need to temporarily add the following config to your SSH config (obviously change the details for your case).
The key is the line "IdentitiesOnly yes" along with an identity file.

```
Host 188.245.194.78
  User root
  IdentityFile ~/.ssh/hetzner_personal_root.pub
  IdentitiesOnly yes
```

Once you can SSH into the host normally, run `just nixify_host <hostname> "code" "<dns name>,<ip address>"`.
For example: `just nixify_host epesooj-code-0001 code "code.akols.com,188.245.194.78"`.

This command requires you to have the key for the Epesooj Host SSH certificate authority.
If you don't have it, contact someone who does.

## Deploying the webring

You should have a `.env` file with the id and deploy key for each script in the webring, as well as a key to deploy the index page to bunny.
When you have this, run `deno task deploy`.
You'll need the API keys required to deploy these.
If you don't have them, contact someone who does.