snuffster/szurubooru
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: clean up

Browse source
This commit is contained in:
Shyam Sunder 2020-06-05 10:29:52 -04:00
parent e7610db054
commit 4f46619b91
4 changed files with 54 additions and 289 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
README.md
View file

@ -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

54
doc/INSTALL.md
View file

@ -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;
}
```

237
doc/LEGACY_INSTALL.md
View file

@ -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
```

49
doc/nginx.vhost.production
View file

@ -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;
}