Add docs using MkDocs

3 files changed, 194 insertions, 0 deletions

diff --git a/docs/running-gathio/configuration.md b/docs/running-gathio/configuration.md
new file mode 100644
index 0000000..cdad0fa
--- /dev/null
+++ b/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`                   | "contact@example.com" | 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: ["test@test.com", "admin@test.com"]                                                                                        |
+
+## `[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. |
diff --git a/docs/running-gathio/customization.md b/docs/running-gathio/customization.md
new file mode 100644
index 0000000..b764138
--- /dev/null
+++ b/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.
+```
diff --git a/docs/running-gathio/installation.md b/docs/running-gathio/installation.md
new file mode 100644
index 0000000..7be73c4
--- /dev/null
+++ b/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.