diff options
| -rw-r--r-- | README.md | 3 | ||||
| -rw-r--r-- | doc/INSTALL.md | 54 | ||||
| -rw-r--r-- | doc/LEGACY_INSTALL.md | 237 | ||||
| -rw-r--r-- | doc/nginx.vhost.production | 49 |
4 files changed, 54 insertions, 289 deletions
@@ -32,7 +32,8 @@ scrubbing](http://sjp.pwn.pl/sjp/;2527372). It is pronounced as *shoorubooru*. It is recommended that you use Docker for deployment. [See installation instructions.](doc/INSTALL.md) -Users who wish to avoid using Docker may find the [old installation instructions](doc/LEGACY_INSTALL.md) helpful. +More installation resources, as well as related projects can be found on the +[GitHub project Wiki](https://github.com/rr-/szurubooru/wiki) ## Screenshots diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 3cb2699..0a109d3 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -120,5 +120,55 @@ user@host:szuru$ docker-compose down 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). + to proxy_pass `http://127.0.0.1:8080`. An example config is shown below: + + ```nginx + # 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; + } + ``` diff --git a/doc/LEGACY_INSTALL.md b/doc/LEGACY_INSTALL.md deleted file mode 100644 index 1e667de..0000000 --- a/doc/LEGACY_INSTALL.md +++ /dev/null @@ -1,237 +0,0 @@ -**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 -``` diff --git a/doc/nginx.vhost.production b/doc/nginx.vhost.production deleted file mode 100644 index 5a95b52..0000000 --- a/doc/nginx.vhost.production +++ /dev/null @@ -1,49 +0,0 @@ -# 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; -} |