Merge pull request #2 from TxtDot/dc09-1

Almost completed docs

docs/docker.md

@@ -0,0 +1,18 @@
+# Docker
+
+If you prefer hosting without Docker, see [Self-Hosting](selfhost.md) instead.
+
+Docker Engine and Docker Compose are required.
+
+Note that built images are not provided via Docker Hub.
+If you can't or don't want to build them on your server
+and don't want to setup a CI/CD system,
+[let us know](https://github.com/txtdot/txtdot/issues),
+we'll consider setting up a GitHub Actions workflow.
+
+```bash
+git clone https://github.com/txtdot/txtdot.git
+cd txtdot
+docker compose build
+docker compose up -d
+```

docs/env.md

@@ -0,0 +1,26 @@
+# Configuring
+
+txtdot can be configured either with environment variables
+or with the `.env` file in the working directory which has higher priority.
+For sample config, see [`.env.example`](https://github.com/TxtDot/txtdot/blob/main/.env.example).
+
+## HOST
+
+Default: `0.0.0.0`
+
+Host where HTTP server should listen for connections.
+Set it to `127.0.0.1` if your txtdot instance is behind reverse proxy,
+`0.0.0.0` otherwise.
+
+## PORT
+
+Default: `8080`
+
+Port where HTTP server should listen for connections.
+
+## REVERSE_PROXY
+
+Default: `false`
+
+Set it to `true` only if your txtdot instance runs behind reverse proxy.
+Needed for processing X-Forwarded headers.

docs/reverse.md

@@ -0,0 +1,102 @@
+# Reverse Proxy
+
+## Nginx
+
+Basically, you just need to set the domain, TLS certificates,
+Host and X-Forwarded headers (so txtdot could know the hostname)
+and pass all requests to txtdot.
+
+```
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+
+    # Replace the domain
+    server_name txt.dc09.ru;
+
+    ssl_certificate ...pem;
+    ssl_certificate_key ...key;
+    # More options here:
+    # https://ssl-config.mozilla.org/#server=nginx&config=modern
+
+    location / {
+        # Replace 8080 port if needed
+        proxy_pass http://127.0.0.1:8080;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+On the official instance, TLS is configured in the main nginx config,
+so we omit these options below.
+
+Nginx serves static files faster than NodeJS, let's configure it:
+
+```
+server {
+    ...
+
+    location /static/ {
+        alias /home/txtdot/src/dist/static/;
+    }
+}
+```
+
+What about rate-limiting? We don't want the hackers to overload our proxy.
+
+The config below rate-limits to 2 requests per second,
+allows to put up to 4 requests into the queue,
+sets the maximum size for zone to 10 megabytes.
+See the [Nginx blog post](https://www.nginx.com/blog/rate-limiting-nginx/) for detailed explanation.
+
+```
+limit_req_zone $binary_remote_addr zone=txtdotapi:10m rate=2r/s;
+
+server {
+    ...
+    location / {
+        limit_req zone=txtdotapi burst=4;
+        ...
+    }
+    ...
+}
+```
+
+Let's put all together.
+Here's our [sample config](https://github.com/TxtDot/txtdot/blob/main/config/nginx.conf):
+
+```
+limit_req_zone $binary_remote_addr zone=txtdotapi:10m rate=2r/s;
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    
+    server_name txt.dc09.ru;
+
+    location / {
+        limit_req zone=txtdotapi burst=4;
+        proxy_pass http://127.0.0.1:8080;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location /static/ {
+        alias /home/txtdot/src/dist/static/;
+    }
+}
+```
+
+## Apache
+
+Coming soon.
+If you are familiar with Apache httpd and want to help,
+write a config here (a small explanation as above also would be great)
+and open a [pull request](https://github.com/txtdot/documentation/pulls).

docs/selfhost.md

@@ -1,11 +1,15 @@
 # Self-Hosting
 
-## Without Docker
+If you prefer hosting with Docker, see [Docker](docker.md) instead.
 
-Install Node and NPM:
+## Install nodejs and npm
+
+For Debian, Ubuntu: packages in the repository are so old,
+consider installing them with [NodeSource](https://github.com/nodesource/distributions#installation-instructions).
+Minimal required version is NodeJS 18.
+
+Other distros:
 ```bash
-# Debian, Ubuntu
-sudo apt install nodejs npm
 # CentOS
 sudo yum install nodejs
 # Arch
@@ -14,26 +18,37 @@ sudo pacman -S nodejs npm
 doas apk add nodejs npm
 ```
 
-Create a user for txtdot, log in:
+## Create a user for txtdot
-```bash
-# Not Alpine (coreutils)
-sudo useradd -r -m -s /sbin/nologin -U txtdot
-sudo -u txtdot -i
 
-# Alpine (busybox)
+Almost all distros except Alpine:
+```bash
+sudo useradd -r -m -s /sbin/nologin -U txtdot
+sudo -u txtdot bash
+```
+
+Alpine Linux with busybox and doas:
+```bash
 doas addgroup -S txtdot
 doas adduser -h /home/txtdot -s /sbin/nologin -G txtdot -S -D txtdot
 doas -u txtdot bash
 ```
 
-Clone the repo: 
+## Build, config and launch
+
+Clone the git repository, cd into it:
 ```bash
 git clone https://github.com/txtdot/txtdot.git src
+cd src
+```
+
+Copy and modify the sample config file (see the [Configuring](env.md) section):
+```bash
+cp .env.example .env
+nano .env
 ```
 
 Install packages, compile TS:
 ```bash
-cd src
 npm install
 npm run build
 ```
@@ -43,14 +58,17 @@ Manually start the server to check if it works (Ctrl+C to exit):
 npm run start
 ```
 
-Log out from txtdot account: `exit`
+Log out from the txtdot account:
+```bash
+exit
+```
 
-### Add txtdot to autostart
+## Add txtdot to autostart
 Either using systemd unit file:
 ```bash
-wget https://github.com/TxtDot/txtdot/blob/main/txtdot.service
+wget https://raw.githubusercontent.com/TxtDot/txtdot/main/config/txtdot.service
 sudo chown root:root txtdot.service
-sudo chmod 755 txtdot.service
+sudo chmod 644 txtdot.service
 sudo mv txtdot.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable txtdot
@@ -59,7 +77,7 @@ sudo systemctl start txtdot
 
 Or using OpenRC script:
 ```bash
-wget -O txtdot https://github.com/TxtDot/txtdot/blob/main/txtdot.init
+wget -O txtdot https://raw.githubusercontent.com/TxtDot/txtdot/main/config/txtdot.init
 doas chown root:root txtdot
 doas chmod 755 txtdot
 doas mv txtdot /etc/init.d/
@@ -75,20 +93,3 @@ sudo crontab -u txtdot -e
 @reboot sleep 10 && cd /home/txtdot/src && npm run start
 # Save the file and exit
 ```
-
-## With Docker
-
-Docker Engine and Docker Compose are required.
-
-Note that built images are not provided via Docker Hub.
-If you can't or don't want to build them on your server
-and don't want to setup a CI/CD system,
-[let us know](https://github.com/txtdot/txtdot/issues),
-we'll consider setting up a GitHub Actions workflow.
-
-```bash
-git clone https://github.com/txtdot/txtdot.git
-cd txtdot
-docker compose build
-docker compose up -d
-```

mkdocs.yml

@@ -1,4 +1,10 @@
 site_name: txtdot
+nav:
+  - "Getting Started": index.md
+  - "Self-Hosting": selfhost.md
+  - "Docker": docker.md
+  - "Configuring": env.md
+  - "Reverse Proxy": reverse.md
 repo_url: https://github.com/txtdot/txtdot
 repo_name: txtdot/txtdot
 theme: