Browse Source

Add license and reset README for rewrite

pull/2/head
sn0w 7 months ago
parent
commit
6c60894199
2 changed files with 25 additions and 159 deletions
  1. 22
    0
      LICENSE
  2. 3
    159
      README.md

+ 22
- 0
LICENSE View File

@@ -0,0 +1,22 @@
Copyright (c) 2017-2018, sn0w
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

+ 3
- 159
README.md View File

@@ -7,8 +7,7 @@ This repository dockerizes it for easier deployment.
<hr>

```cpp
#include <public_domain.h>
#include <std_disclaimer.h>
#include <LICENSE>

/*
* This repository comes with ABSOLUTELY NO WARRANTY
@@ -24,14 +23,6 @@ This repository dockerizes it for easier deployment.

<hr>

## Features

- 100% generic
- Everything is customizable
- Zero special host dependencies
- Configuration is not compile-time
- "It just works"

## Alternatives

If this setup is a bit overwhelming there are a lot of other great dockerfiles
@@ -41,153 +32,6 @@ or guides from the community. A few are linked below. This list is not exhaustiv
- [RX14/iscute.moe](https://github.com/RX14/kurisu.rx14.co.uk/blob/master/services/iscute.moe/pleroma/Dockerfile)
- [rysiek/docker-pleroma](https://git.pleroma.social/rysiek/docker-pleroma)

## Installing Pleroma

- Clone this repository
- Copy `.env.dist` to `.env`
- Edit `.env` (see "Configuring Pleroma" section below)
- Run `./pleroma build` and `./pleroma start`
- Profit!

## Updating Pleroma

Just run `./pleroma build` again and `./pleroma start` afterwards.

You don't need to shutdown pleroma while compiling the new release.

Every time you run `./pleroma build` the script will fetch all upstream changes and checkout `PLEROMA_VERSION`.
This means that setting `PLEROMA_VERSION` to a branch enables rolling-release updates while setting
it to a tag or commit-hash pins the version.

## Maintaining Pleroma

Pleroma maintenance is usually done with premade mix tasks.<br>
You can run these tasks using `./pleroma mix [task] [arguments...]`.<br>
If you need to fix some bigger issues you can also spawn a shell using `./pleroma enter`.

## Customizing Pleroma

Just add your customizations (and their folder structure) to `custom.d`.<br>
They will be mounted and symlinked into the right place when the container starts.<br>
You can even replace/patch pleroma's code with this, because the project is recompiled at startup.<br>

In general: Prepending `custom.d/` to pleroma's customization guides should work all the time.<br>
Check them out in the [official pleroma wiki](https://git.pleroma.social/pleroma/pleroma/wikis/home).

For example: A custom thumbnail now goes into `custom.d/priv/static/instance/thumbnail.jpeg` instead of `priv/static/instance/thumbnail.jpeg`.

Note: Since `custom.d` needs to be accessible at runtime by the pleroma process, the container will automatically chown these files to `$UID:$GID` from your `.env` file.

## Configuring Pleroma

pleroma-docker tries to stay out of your way as much as possible while providing
a good experience for both you and your users. It thus supports multiple
"operation modes" and quite some config variables which you can mix and match.

This guide will explain some of the tricky `.env` file parts as detailed as possible (but you should still read the comments in there).

Since this setup [injects code](https://glitch.sh/sn0w/pleroma-docker/blob/master/docker-config.exs) into pleroma that moves it's configuration into the environment (ref ["The Twelve-Factor App"](https://12factor.net/)),
the built image is 100% reusable and can be shared/replicated across multiple hosts.
To do that just run `./pleroma build` as usual and then tag your image to whatever you want.
Just make sure to start the replicated container with `env_file:` or all required `-e` pairs.

#### Storing Data

Currently all data is stored in subfolders of `DOCKER_DATADIR` which will be bind-mounted into the container by docker.

We'll evaluate named volumes as an option in the future but they're currently not supported.

#### Database (`SCRIPT_DEPLOY_POSTGRES`)

Values: `true` / `false`

By default pleroma-docker deploys a postgresql container and links it to pleroma's container as a zero-config data store. If you already have a postgres database or want to host postgres on a physically different machine set this value to `false`. Make sure to set the `POSTGRES_*` variables when doing that.

#### Reverse Proxy (`SCRIPT_USE_PROXY`)

Values: `traefik` / `nginx` / `manual`

Pleroma is usually run behind a reverse-proxy.
Pleroma-docker gives you multiple options here.

##### Traefik

In traefik-mode we will generate a pleroma container with traefik labels.
These will be picked up at runtime to dynamically create a reverse-proxy
configuration. This should 'just work' if `watch=true` and `exposedByDefault=false` are set in the `[docker]` section of your `traefik.conf`. SSL will also 'just work' once you add a matching `[[acme.domains]]` entry.

##### NGINX

In nginx-mode we will generate a bare nginx container that is linked to the
pleroma container. The nginx container is absolutely unmodified and expects to
be configured by you. The nginx file in [Pleroma's Repository](https://git.pleroma.social/pleroma/pleroma/blob/develop/installation/pleroma.nginx) is a good starting point.

We will mount your configs like this:
```
custom.d/server.nginx -> /etc/nginx/nginx.conf
custom.d/vhost.nginx -> /etc/nginx/conf.d/pleroma.conf
```

To reach your pleroma container from inside nginx use `proxy_pass http://pleroma:4000;`.

Set `SCRIPT_PORT_HTTP` and `SCRIPT_PORT_HTTPS` to the ports you want to listen on.
Specify the ip to bind to in `SCRIPT_BIND_IP`. These values are required.

The container only listens on `SCRIPT_PORT_HTTPS` if `SCRIPT_ENABLE_SSL` is `true`.

##### Apache / httpd

Just like nginx-mode this starts an unmodified apache server that expects to be
configured by you. Again [Pleroma's Config](https://git.pleroma.social/pleroma/pleroma/blob/develop/installation/pleroma-apache.conf) is a good starting point.

We will mount your configs like this:
```
custom.d/server.httpd -> /usr/local/apache2/conf/httpd.conf
custom.d/vhost.httpd -> /usr/local/apache2/conf/extra/httpd-vhosts.conf
```

To reach your pleroma container from inside apache use `ProxyPass [loc] http://pleroma:4000/`.

Again setting `SCRIPT_PORT_HTTP`, `SCRIPT_PORT_HTTPS` and `SCRIPT_BIND_IP` is required.

The container only listens on `SCRIPT_PORT_HTTPS` if `SCRIPT_ENABLE_SSL` is `true`.

##### Manual

In manual mode we do not create any reverse proxy for you.
You'll have to figure something out on your own.

This mode also doesn't bind to any IP or port.
You'll have to forward something to the container's IP.

#### SSL (`SCRIPT_ENABLE_SSL`)

Values: `true` / `false`

If you want to use SSL with your Apache or NGINX containers you'll need a
certificate. Certificates need to be placed into `custom.d` and will be
bind-mounted into the server's container at runtime.

We will mount your certs like this:
```
custom.d/ssl.crt -> /ssl/ssl.crt
custom.d/ssl.key -> /ssl/ssl.key
```

You can reference them in Apache like this:
```apache
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile "/ssl/ssl.crt"
SSLCertificateKeyFile "/ssl/ssl.key"
</VirtualHost>
```

And in NGINX like this:
```nginx
listen 443 ssl;
ssl_certificate /ssl/ssl.crt;
ssl_certificate_key /ssl/ssl.key;
```
## Docs

In traefik-mode and manual-mode these files and the `SCRIPT_ENABLE_SSL` value are ignored.
coming soon tm

Loading…
Cancel
Save