doc: moved documentation to a seperate folder

doc/INSTALL.md

@@ -0,0 +1,115 @@
+This assumes that you have Docker (version 17.05 or greater)
+and Docker Compose (version 1.6.0 or greater) already installed.
+
+### Prepare things
+
+1. Getting `szurubooru`:
+
+    ```console
+    user@host:~$ git clone https://github.com/rr-/szurubooru.git szuru
+    user@host:~$ cd szuru
+    ```
+2. Configure the application:
+
+    ```console
+    user@host:szuru$ cp server/config.yaml.dist server/config.yaml
+    user@host:szuru$ edit server/config.yaml
+    ```
+
+    Pay extra attention to these fields:
+
+    - secret
+    - the `smtp` section.
+
+    You can omit lines when you want to use the defaults of that field.
+
+3. Configure Docker Compose:
+
+    ```console
+    user@host:szuru$ cp doc/example.env .env
+    user@host:szuru$ edit .env
+    ```
+
+    Change the values of the variables in `.env` as needed.
+    Read the comments to guide you. Note that `.env` should be in the root
+    directory of this repository.
+
+### Running the Application
+
+1. Configurations for ElasticSearch:
+
+    You may need to raise the `vm.max_map_count`
+    parameter to at least `262144` in order for the
+    ElasticSearch container to function. Instructions
+    on how to do so are provided
+    [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode).
+
+2. Build or update the containers:
+
+    ```console
+    user@host:szuru$ docker-compose pull
+    user@host:szuru$ docker-compose build --pull
+    ```
+
+    This will build both the frontend and backend containers, and may take
+    some time.
+
+3. Start and stop the the application
+
+    ```console
+    # To start:
+    user@host:szuru$ docker-compose up -d
+    # To monitor (CTRL+C to exit):
+    user@host:szuru$ docker-compose logs -f
+    # To stop
+    user@host:szuru$ docker-compose down
+    ```
+
+### Additional Features
+
+1. **Using a seperate domain to host static files (image content)**
+
+    If you want to host your website on, (`http://example.com/`) but want
+    to serve the images on a different domain, (`http://static.example.com/`)
+    then you can run the backend container with an additional environment
+    variable `DATA_URL=http://static.example.com/`. Make sure that this
+    additional host has access contents to the `/data` volume mounted in the
+    backend.
+
+2. **Setting a specific base URI for proxying**
+
+    Some users may wish to access the service at a different base URI, such
+    as `http://example.com/szuru/`, commonly when sharing multiple HTTP
+    services on one domain using a reverse proxy. In this case, simply set
+    `BASE_URL="/szuru/"` in the frontend container (unless you are hosting your
+    data on a different domain).
+
+    You should set your reverse proxy to proxy `http(s)://example.com/szuru` to
+    `http://<internal IP or hostname of frontend container>/`. For an NGINX
+    reverse proxy, that will appear as:
+
+    ```nginx
+    location /szuru {
+        proxy_http_version 1.1;
+        proxy_pass http://<internal IP or hostname of frontend container>/;
+
+        proxy_set_header Host              $http_host;
+        proxy_set_header Upgrade           $http_upgrade;
+        proxy_set_header Connection        "upgrade";
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Scheme          $scheme;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Script-Name     /szuru;
+    }
+    ```
+
+3. **Preparing for production**
+
+    If you plan on using szurubooru in a production setting, you may opt to
+    use a reverse proxy for added security and caching capabilities. Start
+    by having the client docker listen only on localhost by changing `PORT`
+    in your `.env` file to `127.0.0.1:8080` instead of simply `:8080`. Then
+    configure NGINX (or your caching/reverse proxy server of your choice)
+    to proxy_pass `http://127.0.0.1:8080`. We've also
+    [included an example config](./nginx.vhost.production).

doc/LEGACY_INSTALL.md

@@ -0,0 +1,237 @@
+**This installation guide is deprecated and might be out of date!
+It is recommended that you deploy using [Docker](INSTALL.md) instead.**
+
+This guide assumes Arch Linux. Although exact instructions for other
+distributions are different, the steps stay roughly the same.
+
+### Installing hard dependencies
+
+Szurubooru requires the following dependencies:
+- Python (3.5 or later)
+- Postgres
+- FFmpeg
+- node.js
+
+```console
+user@host:~$ sudo pacman -S postgresql
+user@host:~$ sudo pacman -S python
+user@host:~$ sudo pacman -S python-pip
+user@host:~$ sudo pacman -S ffmpeg
+user@host:~$ sudo pacman -S npm
+user@host:~$ sudo pacman -S elasticsearch
+user@host:~$ sudo pip install virtualenv
+user@host:~$ python --version
+Python 3.5.1
+```
+
+The reason `ffmpeg` is used over, say, `ImageMagick` or even `PIL` is because of
+Flash and video posts.
+
+
+
+### Setting up a database
+
+First, basic `postgres` configuration:
+
+```console
+user@host:~$ sudo -i -u postgres initdb --locale en_US.UTF-8 -E UTF8 -D /var/lib/postgres/data
+user@host:~$ sudo systemctl start postgresql
+user@host:~$ sudo systemctl enable postgresql
+```
+
+Then creating a database:
+
+```console
+user@host:~$ sudo -i -u postgres createuser --interactive
+Enter name of role to add: szuru
+Shall the new role be a superuser? (y/n) n
+Shall the new role be allowed to create databases? (y/n) n
+Shall the new role be allowed to create more new roles? (y/n) n
+user@host:~$ sudo -i -u postgres createdb szuru
+user@host:~$ sudo -i -u postgres psql -c "ALTER USER szuru PASSWORD 'dog';"
+```
+
+
+
+### Setting up elasticsearch
+
+```console
+user@host:~$ sudo systemctl start elasticsearch
+user@host:~$ sudo systemctl enable elasticsearch
+```
+
+### Preparing environment
+
+Getting `szurubooru`:
+
+```console
+user@host:~$ git clone https://github.com/rr-/szurubooru.git szuru
+user@host:~$ cd szuru
+```
+
+Installing frontend dependencies:
+
+```console
+user@host:szuru$ cd client
+user@host:szuru/client$ npm install
+```
+
+`npm` sandboxes dependencies by default, i.e. installs them to
+`./node_modules`. This is good, because it avoids polluting the system with the
+project's dependencies. To make Python work the same way, we'll use
+`virtualenv`. Installing backend dependencies with `virtualenv` looks like
+this:
+
+```console
+user@host:szuru/client$ cd ../server
+user@host:szuru/server$ virtualenv python_modules # consistent with node_modules
+user@host:szuru/server$ source python_modules/bin/activate # enters the sandbox
+(python_modules) user@host:szuru/server$ pip install -r requirements.txt # installs the dependencies
+```
+
+
+
+### Preparing `szurubooru` for first run
+
+1. Compile the frontend:
+
+    ```console
+    user@host:szuru$ cd client
+    user@host:szuru/client$ node build.js
+    ```
+
+    You can include the flags `--no-transpile` to disable the JavaScript
+    transpiler, which provides compatibility with older browsers, and
+    `--debug` to generate JS source mappings.
+
+2. Configure things:
+
+    ```console
+    user@host:szuru/client$ cd ..
+    user@host:szuru$ mv server/config.yaml.dist .
+    user@host:szuru$ cp config.yaml.dist config.yaml
+    user@host:szuru$ vim config.yaml
+    ```
+
+    Pay extra attention to these fields:
+
+    - data directory,
+    - data URL,
+    - database,
+    - the `smtp` section.
+
+3. Upgrade the database:
+
+    ```console
+    user@host:szuru/client$ cd ../server
+    user@host:szuru/server$ source python_modules/bin/activate
+    (python_modules) user@host:szuru/server$ alembic upgrade head
+    ```
+
+    `alembic` should have been installed during installation of `szurubooru`'s
+    dependencies.
+
+4. Run the tests:
+
+    ```console
+    (python_modules) user@host:szuru/server$ pytest
+    ```
+
+It is recommended to rebuild the frontend after each change to configuration.
+
+
+
+### Wiring `szurubooru` to the web server
+
+`szurubooru` is divided into two parts: public static files, and the API. It
+tries not to impose any networking configurations on the user, so it is the
+user's responsibility to wire these to their web server.
+
+The static files are located in the `client/public/data` directory and are
+meant to be exposed directly to the end users.
+
+The API should be exposed using WSGI server such as `waitress`, `gunicorn` or
+similar. Other configurations might be possible but I didn't pursue them.
+
+API calls are made to the relative URL `/api/`. Your HTTP server should be
+configured to proxy this URL format to the WSGI server. Some users may prefer
+to use a dedicated reverse proxy for this, to incorporate additional features
+such as load balancing and SSL.
+
+Note that the API URL in the virtual host configuration needs to be the same as
+the one in the `config.yaml`, so that client knows how to access the backend!
+
+#### Example
+
+In this example:
+
+- The booru is accessed from `http://example.com/`
+- The API is accessed from `http://example.com/api`
+- The API server listens locally on port 6666, and is proxied by nginx or apache
+- The static files are served from `/srv/www/booru/client/public/data`
+
+You can use either nginx or apache to serve your static content and proxy the api server.
+Choose whichever you prefer, but don't use both.
+
+**nginx configuration**:
+
+```nginx
+server {
+    listen 80;
+    server_name example.com;
+
+    location ~ ^/api$ {
+        return 302 /api/;
+    }
+    location ~ ^/api/(.*)$ {
+        if ($request_uri ~* "/api/(.*)") { # preserve PATH_INFO as-is
+            proxy_pass http://127.0.0.1:6666/$1;
+        }
+    }
+    location / {
+        root /srv/www/booru/client/public;
+        try_files $uri /index.htm;
+    }
+}
+```
+
+**apache configuration**:
+
+```apache
+<VirtualHost *:80>
+    ServerName example.com
+
+    Redirect 302 /api /api/
+
+    ProxyPreserveHost On
+    ProxyPass /api/ http://127.0.0.1:6666/
+    ProxyPassReverse /api/ http://127.0.0.1:6666/
+
+    DocumentRoot "/srv/www/booru/client/public"
+    FallbackResource /index.htm
+    AllowEncodedSlashes On
+</VirtualHost>
+```
+
+**`config.yaml`**:
+
+```yaml
+data_url: 'http://example.com/data/'
+data_dir: '/srv/www/booru/client/public/data'
+```
+
+To run the server using `waitress`:
+
+```console
+user@host:szuru/server$ source python_modules/bin/activate
+(python_modules) user@host:szuru/server$ pip install waitress
+(python_modules) user@host:szuru/server$ waitress-serve --port 6666 szurubooru.facade:app
+```
+
+or `gunicorn`:
+
+```console
+user@host:szuru/server$ source python_modules/bin/activate
+(python_modules) user@host:szuru/server$ pip install gunicorn
+(python_modules) user@host:szuru/server$ gunicorn szurubooru.facade:app -b 127.0.0.1:6666
+```

doc/example.env

@@ -0,0 +1,18 @@
+# Database credentials
+POSTGRES_USER=szuru
+POSTGRES_PASSWORD=changeme
+
+# This shows up on the homescreen, indicating build information
+BUILD_INFO=latest
+
+# Port to expose HTTP service
+# Set to 127.0.0.1:8080 if you wish to reverse-proxy the docker's port,
+# otherwise the port specified here will be publicly accessible
+PORT=8080
+
+# Directory to store image data
+MOUNT_DATA=/var/local/szurubooru/data
+
+# Directory to store database files
+MOUNT_SQL=/var/local/szurubooru/sql
+

doc/nginx.vhost.production

@@ -0,0 +1,49 @@
+# example for a production vhost for szurubooru.
+# ideally, use ssl termination + cdn with a provider such as cloudflare.
+# modify as needed!
+
+# rate limiting zone
+# poor man's ddos protection, essentially
+limit_req_zone $binary_remote_addr zone=throttle:10m rate=25r/s;
+
+# www -> non-www
+server {
+  listen 80;
+  listen [::]:80;
+  server_tokens off;
+  server_name www.example.com
+  return 301 http://example.com$request_uri;
+}
+
+server {
+  server_name example.com;
+  client_max_body_size 100M;
+  client_body_timeout 30s;
+  server_tokens off;
+  location / {
+    limit_req zone=throttle burst=5 delay=3;
+    proxy_http_version 1.1;
+    proxy_pass http://127.0.0.1:8080;
+    proxy_set_header Host $http_host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Scheme $scheme;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Script-Name /szuru;
+    error_page 500 501 502 504 505 506 507 508 509 510 511 @err;
+    error_page 503 @throttle;
+  }
+
+  location @err {
+    return 500 "server error. please try again later.";
+    default_type text/plain;
+  }
+  location @throttle {
+    return 503 "we've detected abuse on your ip. please wait and try again later.";
+    default_type text/plain;
+  }
+  listen 80;
+  listen [::]:80;
+}