Merge pull request #137 from lowercasename/rk/docs

Add docs using MkDocs

README.md

@@ -4,10 +4,10 @@
 
 [![Build status](https://github.com/lowercasename/gathio/actions/workflows/deploy.yaml/badge.svg)](https://github.com/lowercasename/gathio/actions/workflows/deploy.yaml)
 
-Self-destructing, shareable, no-registration event pages.
+A simple, federated, privacy-first event hosting platform.
 
-You can use the publicly hosted version [here](https://gath.io).
+You can use the flagship publicly hosted version [here](https://gath.io).
 
-# Installation
+# Documentation
 
-See [the Wiki](https://github.com/lowercasename/gathio/wiki/install) for installation instructions.
+To learn more about how to use Gathio, or how to set up your own instance, vist our [documentation site](https://docs.gath.io). If the site isn't working, the source documentation files are in the [`docs/` directory](https://github.com/lowercasename/gathio/tree/main/docs).

deploy.sh

@@ -16,4 +16,9 @@ NODE_ENV=development pnpm install
 # TypeScript and don't expect any more errors.
 pnpm build || true
 pm2 reload ecosystem.config.cjs production
-pm2 save 
+pm2 save
+
+# Build the docs and deploy
+pip install mkdocs
+pip install mkdocs-material
+mkdocs build -d ~/gathio-docs

docs/index.md

@@ -0,0 +1,16 @@
+# Getting started
+
+Gathio is a simple, federated, privacy-first event hosting platform.
+
+You can use the publicly hosted, flagship instance of Gathio at
+[https://gath.io](https://gath.io), and you can also run your very own instance
+on your own server.
+
+These docs are here to:
+
+-   Explain the more esoteric or complex features of Gathio
+-   Help you set up, customize, and run Gathio on your own system
+
+## Documentation
+
+The docs are stored in the `docs/` folder in the Git repository and are built with [MkDocs](https://www.mkdocs.org/).

docs/running-gathio/configuration.md

@@ -0,0 +1,46 @@
+# Configuration
+
+Gathio is configured through a config file located at `config/config.toml`. The config options are as follows:
+
+## `[general]` section
+
+| Option                    | Default Value         | Description                                                                                                                                                                                                                                           |
+| ------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `domain`                  | "localhost:3000"      | Your instance domain. If there is a port it should be 'domain.com:port', but otherwise just 'domain.com'.                                                                                                                                             |
+| `port`                    | "3000"                | The port on which Gathio will serve the site.                                                                                                                                                                                                         |
+| `email`                   | "[email protected]" | Your contact email, from which the emails Gathio sends are addressed.                                                                                                                                                                                 |
+| `site_name`               | "Gathio"              | Your instance's name, shown in various places on the frontend.                                                                                                                                                                                        |
+| `is_federated`            | true                  | If set to `true`, ActivityPub federation features will be enabled.                                                                                                                                                                                    |
+| `delete_after_days`       | 7                     | Events will be deleted this many days after they have ended. Set to 0 to disable automatic deletion (old events will never be deleted).                                                                                                               |
+| `email_logo_url`          | ""                    | If left blank, this defaults to https://yourdomain.com/images/gathio-email-logo.gif. Set a full URL here to change it to your own logo (or just change the file itself).                                                                              |
+| `show_kofi`               | false                 | Show a Ko-Fi box to donate money to Raphael (Gathio's creator) on the front page.                                                                                                                                                                     |
+| `show_public_event_list`  | false                 | Show a list of events and groups on the front page which have been marked as 'Display this event/group on the public event/group list'. This list becomes the home page, and the about page with information on Gathio remains available at `/about`. |
+| `mail_service`            | "nodemailer"          | Which mail service to use to send emails to hosts and attendees. Options are 'nodemailer' or 'sendgrid'.                                                                                                                                              |
+| `creator_email_addresses` | []                    | An array of email addresses which are permitted to create events. If this is empty, anyone can create events. For example: ["[email protected]", "[email protected]"]                                                                                        |
+
+## `[database]` section
+
+| Option        | Default Value                      | Description                                                                                                                 |
+| ------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `mongodb_url` | "mongodb://localhost:27017/gathio" | Set up for a locally running MongoDB connection. Change this to 'mongodb://mongo:27017/gathio' for a Dockerised connection. |
+
+## `[nodemailer]` section
+
+| Option          | Default Value | Description                   |
+| --------------- | ------------- | ----------------------------- |
+| `smtp_server`   | ""            | The Nodemailer SMTP server.   |
+| `smtp_port`     | ""            | The Nodemailer SMTP port.     |
+| `smtp_username` | ""            | The Nodemailer SMTP username. |
+| `smtp_password` | ""            | The Nodemailer SMTP password. |
+
+## `[sendgrid]` section
+
+| Option    | Default Value | Description           |
+| --------- | ------------- | --------------------- |
+| `api_key` | ""            | The Sendgrid API key. |
+
+## `[[static_pages]]` sections
+
+| Option         | Description                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------- |
+| `static_pages` | Links to static pages, which will be displayed in the footer. See [Customization](customization.md) for more. |

docs/running-gathio/customization.md

@@ -0,0 +1,46 @@
+# Customization
+
+A Gathio installation can be customized, mostly through the `config.toml` file (see [Configuration](configuration.md) for more details). Some information on specific customization techniques is set out here.
+
+## Static pages
+
+Static pages are Markdown pages which are linked in the footer of your instance's frontend pages.
+
+Create static pages as Markdown files in the `static/` directory. For instance, a privacy policy page might look like this:
+
+```markdown
+# static/privacy-policy.md
+
+This is an example privacy policy. It **supports Markdown!**
+```
+
+In `config.toml`, for each static page you create, add a configuration block that looks like this:
+
+```toml
+[[static_pages]]
+title = "Privacy Policy"
+path = "/privacy"
+filename = "privacy-policy.md"
+```
+
+The filename is relative to the `static/` directory.
+
+Paths can be internal (beginning with a slash) or absolute (beginning with https://). For internal paths, the path value will correspond to the page's frontend path, so be aware that setting it to the same path as an existing page (for instance `/new` or `/events`) will result in undefined behaviour and should be avoided.
+
+The title will appear at the top of the page and in the footer menu.
+
+## Instance description
+
+The instance description is a block of text which appears at the top of the public event list page (which is the home page on instances where `show_public_event_list` is set to `true`) and the 'About' page (which is the home page on instances where `show_public_event_list` is set to `false`).
+
+The instance description is rendered from the Markdown file `static/instance-description.md`; if this file is missing, it will default to a generic line of text.
+
+Within the instance description, you can use most Markdown formatting, as on static pages, and also you can supply the template string `{{ siteName }}`, which will be converted to the value of `site_name` as specified in `config.toml`.
+
+The default instance description is:
+
+```markdown
+# static/instance-description.md
+
+**{{ siteName }}** is running on Gathio — a simple, federated, privacy-first event hosting platform.
+```

docs/running-gathio/installation.md

@@ -0,0 +1,102 @@
+# Installation
+
+Gathio can be set up to run on your own server in two ways - as a self-hosted service, or via Docker.
+
+## Self-hosting on Linux or macOS
+
+### Prerequisites
+
+-   [Node.js](https://nodejs.org/en/) v18 or greater
+-   [MongoDB](https://www.mongodb.com/docs/manual/administration/install-on-linux/#std-label-install-mdb-community-edition-linux)
+
+### Ubuntu
+
+Let's suppose we're installing on a fresh Ubuntu system.
+
+First, let's get the code:
+
+```
+$ cd /srv/
+$ sudo git clone https://github.com/lowercasename/gathio/
+```
+
+We'll need to install [pnpm](https://pnpm.io/) for this:
+
+```
+$ curl -fsSL https://get.pnpm.io/install.sh | sh -
+```
+
+pnpm installation instructions for [other systems](https://pnpm.io/installation) are available.
+
+Now, we'll install the dependencies:
+
+```
+$ cd gathio
+$ pnpm install
+$ pnpm build
+```
+
+Let's copy the config file in place:
+
+```
+$ cp config/config.example.toml config/config.toml
+```
+
+We can edit this file if needed, as it contains settings which will need to be adjusted to your local setup to successfully format emails.
+
+```
+$ $EDITOR config/config.toml
+```
+
+Either way, we'll need to have MongoDB running. Follow the [MongoDB Community Edition Ubuntu instructions](https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu), which are probably what you want.
+
+Next, let's create a dedicated user:
+
+```
+$ sudo adduser --home /srv/gathio --disabled-login gathio
+$ sudo chown -R gathio:gathio /srv/gathio
+```
+
+Next, we'll copy the systemd service and reload systemd
+
+```
+$ sudo cp gathio.service /etc/systemd/system/
+$ sudo systemctl daemon-reload
+```
+
+Finally, we can start gathio:
+
+```
+$ sudo systemctl start gathio
+```
+
+It should now be listening on port 3000:
+
+```
+$ sudo netstat -tunap | grep LISTEN
+[...]
+tcp        0      0 0.0.0.0:22              0.0.0.0:*               LISTEN      952/sshd
+tcp6       0      0 :::3000                 :::*                    LISTEN      5655/node
+[...]
+```
+
+(this doesn't mean it's only listening on IPv6, because sockets under Linux are
+dual-stack by default...)
+
+It is now available on port 3000, and we can continue by setting up a reverse
+proxy, which allows us to make it available on another port, or from another
+server; and to enable TLS on the connection (see for example [Linode's guide on
+the subject](https://www.linode.com/docs/web-servers/nginx/use-nginx-reverse-proxy/#configure-nginx))
+
+## Docker
+
+The easiest way to run Gathio using Docker is by using the provided `docker-compose` configuration.
+Ensure that the `node_modules` folder does not exist in the `gathio` directory before starting up the
+Docker container.
+
+```
+cd gathio
+docker-compose up -d --build
+```
+
+Gathio should now be running on `http://localhost:3000`, and storing data in a Docker volume.

docs/using-gathio/fediverse.md

@@ -0,0 +1,35 @@
+# Federation
+
+This document contains instructions for how you can expect to interact with Gathio from various ActivityPub-compatible federated services.
+
+## Gathio is federated!
+
+While many events are hosted on the main server, https://gath.io, anyone can use the code available at this very Github repo and set up their own server. So there exist multiple Gathio instances on the Fediverse.
+
+## Interact from your own account, no signup needed
+
+The driving force behind all of this is: while you need to sign up for an account to _create_ an event, RSVP'ing, commenting, and following event updates doesn't require any signup. You can just subscribe to the account from your Fediverse service of choice and interact with it like you normally would.
+
+## Mastodon
+
+Each event created on Gathio has a randomly-generated handle that looks something like `@[email protected]`. If you search for this like you search for any user, the account will pop up in your search results and you can follow it. The moment you follow it, two things happen:
+
+1. If the event allows for people to RSVP, you'll get a DM with a poll asking if you are going to attend. If you vote "Yes" in the poll, your @ handle on your instance will be listed on the event page and it will link back to your Mastodon profile. (The following gif shows this flow in action.) If you RSVP then you will be DMed when the organiser changes any details about the event.
+
+    [![](https://tinysubversions.com/pics/mastodon-01.gif)](https://tinysubversions.com/pics/mastodon-01.gif)
+
+2. Regardless of whether you RSVP, following the account means that you will see any updates made by the organiser in your home timeline, like following any normal account. The event account will also automatically boost any conversation about the event so you can see what people are talking about. (This is subject to the same moderation as any Gathio event: if the event organiser deletes the comment from the event page, then the boost will be un-boosted as well.)
+
+If you'd like to comment on the event, you can simply @ the event handle. If the event organiser has enabled commenting on the event, then your comment will automatically appear on the "comments" section of the page. Comments made via @ notification _must_ be public or unlisted, since all Gathio events are public and we don't want to post your private message where everyone can see. If you try to make a DM comment, you'll get a reply back saying that you should contact the event organiser directly.
+
+## Friendica
+
+On Friendica, you can search for the account and add it as a contact. If you do this, then you'll get an event in your "Latest activity" notifications. The event will have the standard check box to RSVP. If you click that, you'll be RSVP'ed in your own local calendar. If the event organiser has enabled RSVPs, then you'll also be listed on the event page itself with your handle and a link to your Friendica profile page.
+
+The event will also show up in your events calendar!
+
+[![](https://tinysubversions.com/pics/friendica-01.gif)](https://tinysubversions.com/pics/friendica-01.gif)
+
+## Technical specification
+
+For developers and maintainers, the [technical specification](https://github.com/lowercasename/gathio/blob/main/FEDERATION.md) defines the expected behaviour of federation on Gathio instances.

mkdocs.yml

@@ -0,0 +1,2 @@
+site_name: Gathio
+theme: material