Many changes
Update everything (I may have forgotten a few details however) Split installation documentation in many parts, and make it so that you only read what you need to read. Left menu to quickly go to another page. Remove the i18n docs as it was outdated and it duplicated contribute.joinplu.me
This commit is contained in:
Baptiste Gelez
parent
92977a68ce
commit
e1b51db4df
38 changed files with 1121 additions and 697 deletions
31
config.rb
31
config.rb
|
|
@ -12,41 +12,10 @@ activate :autoprefixer do |prefix|
|
|||
prefix.browsers = "last 2 versions"
|
||||
end
|
||||
|
||||
# Layouts
|
||||
# https://middlemanapp.com/basics/layouts/
|
||||
|
||||
# Per-page layout changes
|
||||
page '/*.xml', layout: false
|
||||
page '/*.json', layout: false
|
||||
page '/*.txt', layout: false
|
||||
|
||||
# With alternative layout
|
||||
# page '/path/to/file.html', layout: 'other_layout'
|
||||
|
||||
# Proxy pages
|
||||
# https://middlemanapp.com/advanced/dynamic-pages/
|
||||
|
||||
# proxy(
|
||||
# '/this-page-has-no-template.html',
|
||||
# '/template-file.html',
|
||||
# locals: {
|
||||
# which_fake_page: 'Rendering a fake page with a local variable'
|
||||
# },
|
||||
# )
|
||||
|
||||
# Helpers
|
||||
# Methods defined in the helpers block are available in templates
|
||||
# https://middlemanapp.com/basics/helper-methods/
|
||||
|
||||
# helpers do
|
||||
# def some_helper
|
||||
# 'Helping'
|
||||
# end
|
||||
# end
|
||||
|
||||
# Build-specific configuration
|
||||
# https://middlemanapp.com/advanced/configuration/#environment-specific-settings
|
||||
|
||||
configure :build do
|
||||
activate :minify_css
|
||||
activate :minify_javascript
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
---
|
||||
title: API documentation
|
||||
icon: code
|
||||
summary: Plume can be extended by other applications thanks to a REST API.
|
||||
---
|
||||
|
||||
## Getting an API token
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
---
|
||||
title: plm CLI reference
|
||||
icon: terminal
|
||||
summary: 'plm is a little CLI tool that can help you to manage your instance from the
|
||||
command line if you are admin of an instance.'
|
||||
---
|
||||
|
||||
If any required argument is ommitted, you will be asked to input manually.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,10 @@
|
|||
<nav>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="/">Plume documentation</a>
|
||||
<a href="https://joinplu.me"><img src="/images/logo.svg" alt="Plume logo">Plume</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="/">Documentation</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="https://contribute.joinplu.me/">Contribute</a>
|
||||
|
|
|
|||
16
source/_nav_item.erb
Normal file
16
source/_nav_item.erb
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
<% if items.size > 0 %>
|
||||
<ul>
|
||||
<% items.each do |i| %>
|
||||
<li>
|
||||
<a href="<%= i.url %>"><%= i.data.title %></a>
|
||||
<%= partial :nav_item, :locals => {
|
||||
:items => resources.select{ |r|
|
||||
r.url.split("/").size == i.url.split("/").size + 1 &&
|
||||
r.url.start_with?(i.url)
|
||||
},
|
||||
:resources => resources
|
||||
} %>
|
||||
</li>
|
||||
<% end %>
|
||||
</ul>
|
||||
<% end %>
|
||||
|
|
@ -1,89 +1,118 @@
|
|||
---
|
||||
title: Development Guide
|
||||
icon: git-merge
|
||||
summary: 'How to install Plume on your computer and make changes to the source code.
|
||||
This guide also gives you tips for making debugging and testing easier.'
|
||||
priority: 2
|
||||
---
|
||||
|
||||
## Installing the development environment
|
||||
|
||||
Please refer to the [installation guide](/installation).
|
||||
Please refer to the [installation guide](/installation). Choose to compile Plume
|
||||
from source when asked. Instead of using `cargo install`, use `cargo run` which
|
||||
starts a freshly compiled debugging version of Plume.
|
||||
|
||||
## Testing the federation
|
||||
|
||||
To test the federation, you'll need to setup another database (see "Setup the database"),
|
||||
also owned by the "plume" user, but with a different name. Then, you'll need to run the
|
||||
migrations for this database too.
|
||||
To test the federation, you'll need to setup another database,
|
||||
also owned by the "plume" user, but with a different name. Then, you'll need to setup
|
||||
this instance too.
|
||||
|
||||
The easiest way to do it is probably to install `plm` and `plume` globally (as explained
|
||||
[here](/installation/with/source-code)), but with the `--debug` flag to avoid long compilation
|
||||
times. Then create a copy of your `.env` file in another directory, and change the `DATABASE_URL`
|
||||
and `ROCKET_PORT` variables. Then copy the migration files in this new directory and run them.
|
||||
|
||||
```
|
||||
diesel migration run --database-url postgres://plume:plume@localhost/my_other_plume_db
|
||||
diesel migration run
|
||||
```
|
||||
|
||||
To run this other instance, you'll need to give two environment variables:
|
||||
Setup the new instance with `plm` [as explained here](/installation/config).
|
||||
|
||||
- `ROCKET_PORT`, the port on which your app will run
|
||||
- `DB_NAME`, the name of the database you just created
|
||||
Now, all you need for your two instances to be able to communicate is a fake domain
|
||||
name with HTTPS for each of them. The first step to have that on your local machine is
|
||||
to edit your `/etc/hosts` file, to create two new aliases by adding the following lines.
|
||||
|
||||
```
|
||||
ROCKET_PORT=3033 DB_NAME=my_other_plume_db cargo run
|
||||
127.0.0.1 plume.one
|
||||
127.0.0.1 plume.two
|
||||
```
|
||||
|
||||
If you don't want to setup HTTPS locally, you can also disable it by running your instance with `USE_HTTPS=0` set.
|
||||
Now, we need to create SSL certificates for each of these domains. We will use `mkcert`
|
||||
for this purpose. Here are [the instructions to install it](https://github.com/FiloSottile/mkcert#installation).
|
||||
Once you installed it, run.
|
||||
|
||||
```
|
||||
USE_HTTPS=0 cargo run
|
||||
```bash
|
||||
mkcert -install
|
||||
mkcert plume.one plume.two
|
||||
```
|
||||
|
||||
## Making a Pull Request
|
||||
To create an upstream fork of the repository in GitHub, click "Fork" in the top right button on the main page of the [Plume repository](https://github.com/Plume-org/Plume). Now, in the command line, set another remote for the repository by running the following command, replacing `myname` with the name under which you forked the repo. You can use another name besides `upstream` if you prefer. Using [SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) is recommended.
|
||||
Finally, we need a reverse proxy to load these certificates and redirect to the correct Plume instance for each domain.
|
||||
We will use Caddy here as it is really simple to configure, but if you are more at ease with something else you can also
|
||||
use alternatives.
|
||||
|
||||
To install Caddy, please refer to [their website](https://caddyserver.com/download). Then create
|
||||
a file called `Caddyfile` in the same directory you ran `mkcert` and write this inside.
|
||||
|
||||
```
|
||||
git remote add upstream git@github.com/myname/Plume.git
|
||||
# Alt # git remote add upstream https://github.com/myname/Plume.git
|
||||
plume.one:443 {
|
||||
bind 127.0.0.1
|
||||
proxy / 127.0.0.1:7878 {
|
||||
transparent
|
||||
}
|
||||
tls plume.one+1.pem plume.one+1-key.pem
|
||||
}
|
||||
|
||||
plume.two:443 {
|
||||
bind 127.0.0.1
|
||||
proxy / 127.0.0.1:8787 {
|
||||
transparent
|
||||
}
|
||||
tls plume.one+1.pem plume.one+1-key.pem
|
||||
}
|
||||
```
|
||||
|
||||
Now, make any changes to the code you want. After committing your changes, push to the upstream fork. Once your changes are made, visit the GitHub page for your fork and select "New pull request". Add descriptive text, any issue numbers using hashtags to reference the issue number, screenshots of your changes if relevant, a description of how you tested your changes, and any other information that will help the project maintainers be able to quickly accept your pull requests.
|
||||
Eventually replace the ports in the `proxy` blocks by the one of your two instances, and
|
||||
then run `caddy`. You can now open your browser and load `https://plume.one` and `https://plume.two`.
|
||||
|
||||
The project maintainers may suggest further changes to improve the pull request even more. After implementing this locally, you can push to your upstream fork again and the changes will immediately show up in the pull request after pushing. Once all the suggested changes are made, the pull request may be accepted. Thanks for contributing.
|
||||
# Running tests
|
||||
|
||||
## When working with Tera templates
|
||||
To run tests of `plume-models` use `RUST_TEST_THREADS=1`, otherwise tests are run
|
||||
concurrently, which causes error because they all use the same database.
|
||||
|
||||
When working with the interface, or any message that will be displayed to the final user, keep in mind that Plume is an internationalized software. To make sure that the parts of the interface you are changing are translatable, you should:
|
||||
# Internationalization
|
||||
|
||||
- Use the `_` and `_n` filters instead of directly writing strings in your HTML markup
|
||||
- Add the strings to translate to the `po/plume.pot` file
|
||||
To mark a string as translatable wrap it in the `i18n!` macro. The first argument
|
||||
should be the catalog to load translations from (usually `ctx.1` in templates), the
|
||||
second the string to translate. You can specify format arguments after a `;`.
|
||||
|
||||
Here is an example: let's say we want to add two strings, a simple one and one that may deal with plurals. The first step is to add them to whatever template we want to display them in:
|
||||
If your string vary depending on the number of elements, provide the plural version
|
||||
as the third arguments, and the number of element as the first format argument.
|
||||
|
||||
```jinja
|
||||
<p>{{ "Hello, world!" | _ }}</p>
|
||||
You can find example uses of this macro [here](https://github.com/Plume-org/gettext-macros#example)
|
||||
|
||||
<p>{{ "You have {{ count }} new notifications" | _n(singular="You have one new notification", count=n_notifications) }}</p>
|
||||
```
|
||||
# Working with the front-end
|
||||
|
||||
As you can see, the `_` doesn't need any special argument to work, but `_n` requires `singular` (the singular form, in English) and `count` (the number of items, to determine which form to use) to be present. Note that any parameters given to these filters can be used as regular Tera variables inside of the translated strings, like we are doing with the `count` variable in the second string above.
|
||||
When working with the front-end, we try limit our use of JavaScript as much as possible.
|
||||
Actually, we are not even using JavaScript since our front-end also uses Rust thanks to WebAssembly.
|
||||
But we want Plume to work with as little JavaScript as possible, since reading a post (Plume's first goal)
|
||||
shouldn't require a lot of interactions with the page.
|
||||
|
||||
The second step is to add them to POT file. To add a simple message, just do:
|
||||
When editing SCSS files, it is good to know that they are compiled by `cargo` too. But `cargo` can be
|
||||
a bit slow, since it recompiles all of Plume every time, not only the SCSS files. A workaround is to run
|
||||
`cargo run` in the background, and use `cargo build` to compile your SCSS, then kill it before the end of
|
||||
the build. To know when your SCSS have been compiled, wait for cargo to tell you it is compiling `plume(bin)`
|
||||
and not `plume(build)` (next to the progress bar).
|
||||
|
||||
```po
|
||||
msgid "Hello, world" # The string you used with your filter
|
||||
msgstr "" # Always empty
|
||||
```
|
||||
Also, templates are using the Ructe syntax, which is a mix of Rust and HTML. They are compiled to Rust
|
||||
and embedded in Plume, which means you have to re-run `cargo` everytime you make a change to the templates.
|
||||
|
||||
For plural forms, the syntax is a bit different:
|
||||
|
||||
```po
|
||||
msgid "You have one new notification" # The singular form
|
||||
msgid_plural "You have {{ count }} new notifications" # The plural one
|
||||
msgstr[0] ""
|
||||
msgstr[1] ""
|
||||
```
|
||||
|
||||
And that's it! Once these new messages will have been translated, they will correctly be displayed in the requested locale!
|
||||
|
||||
## Code Style
|
||||
# Code Style
|
||||
|
||||
For Rust, use the standard style. `rustfmt` can help you keeping your code clean.
|
||||
|
||||
For CSS, the only rule is to use One True Brace Style.
|
||||
For SCSS, the only rules are to use One True Brace Style and two spaces to indent code.
|
||||
|
||||
For JavaScript, we use [the JavaScript Standard Style](https://standardjs.com/).
|
||||
|
||||
For HTML/Tera templates, we use HTML5 syntax.
|
||||
For HTML/Ructe templates, we use HTML5 syntax.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ services:
|
|||
volumes:
|
||||
- "./data/postgres:/var/lib/postgresql/data"
|
||||
plume:
|
||||
build: .
|
||||
image: plumeorg/plume
|
||||
env_file: .env
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
---
|
||||
title: Useful Environment Variables
|
||||
icon: file-text
|
||||
summary: 'Plume uses environment variable to configure instances. You can use them
|
||||
to configure the database, or the HTTP interface for instance.'
|
||||
---
|
||||
|
||||
Plume relies on some environment variables for some configuration options. You can either set them before
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
---
|
||||
title: How Plume Federates
|
||||
icon: send
|
||||
summary: 'A summary of the standards Plume uses to federate, how they are implemented,
|
||||
and which parts of these standards are available or not in Plume.'
|
||||
---
|
||||
|
||||
To federate with other Fediverse software (and itself), Plume uses various
|
||||
|
|
|
|||
90
source/images/logo.svg
Normal file
90
source/images/logo.svg
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||
|
||||
<svg
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||
xmlns:cc="http://creativecommons.org/ns#"
|
||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
width="512"
|
||||
height="512"
|
||||
viewBox="0 0 135.46666 135.46667"
|
||||
version="1.1"
|
||||
id="svg169"
|
||||
inkscape:version="0.92.3 (2405546, 2018-03-11)"
|
||||
sodipodi:docname="plumeFeather.svg">
|
||||
<title
|
||||
id="title8">Plume Logo - Feather</title>
|
||||
<defs
|
||||
id="defs163" />
|
||||
<sodipodi:namedview
|
||||
id="base"
|
||||
pagecolor="#ffffff"
|
||||
bordercolor="#666666"
|
||||
borderopacity="1.0"
|
||||
inkscape:pageopacity="0.0"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:zoom="1.4"
|
||||
inkscape:cx="126.20524"
|
||||
inkscape:cy="304.85245"
|
||||
inkscape:document-units="px"
|
||||
inkscape:current-layer="layer1"
|
||||
showgrid="false"
|
||||
units="px"
|
||||
inkscape:window-width="1200"
|
||||
inkscape:window-height="1577"
|
||||
inkscape:window-x="3752"
|
||||
inkscape:window-y="-8"
|
||||
inkscape:window-maximized="1"
|
||||
inkscape:pagecheckerboard="true" />
|
||||
<metadata
|
||||
id="metadata166">
|
||||
<rdf:RDF>
|
||||
<cc:Work
|
||||
rdf:about="">
|
||||
<dc:format>image/svg+xml</dc:format>
|
||||
<dc:type
|
||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
||||
<dc:title>Plume Logo - Feather</dc:title>
|
||||
<dc:date>2018/10/07</dc:date>
|
||||
<dc:creator>
|
||||
<cc:Agent>
|
||||
<dc:title>Abdullah Tarawneh (trwnh.com)</dc:title>
|
||||
</cc:Agent>
|
||||
</dc:creator>
|
||||
<dc:contributor>
|
||||
<cc:Agent>
|
||||
<dc:title>trwnh</dc:title>
|
||||
</cc:Agent>
|
||||
</dc:contributor>
|
||||
<dc:description>A Plume concept logo, with a soft stylized feather. Solid path, no fill.</dc:description>
|
||||
<cc:license
|
||||
rdf:resource="http://creativecommons.org/publicdomain/zero/1.0/" />
|
||||
</cc:Work>
|
||||
<cc:License
|
||||
rdf:about="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<cc:permits
|
||||
rdf:resource="http://creativecommons.org/ns#Reproduction" />
|
||||
<cc:permits
|
||||
rdf:resource="http://creativecommons.org/ns#Distribution" />
|
||||
<cc:permits
|
||||
rdf:resource="http://creativecommons.org/ns#DerivativeWorks" />
|
||||
</cc:License>
|
||||
</rdf:RDF>
|
||||
</metadata>
|
||||
<g
|
||||
inkscape:label="Layer 1"
|
||||
inkscape:groupmode="layer"
|
||||
id="layer1"
|
||||
transform="translate(0,-161.53332)">
|
||||
<path
|
||||
style="fill:none;fill-opacity:1;stroke:#7765e3;stroke-width:4.2751441;stroke-linecap:square;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;paint-order:normal"
|
||||
d="M 11.343027,288.41445 C 1.112349,298.81005 0.43838995,295.69058 4.3446684,285.90553 L 16.157848,265.54671 c 1.615107,0.40548 13.891904,-55.26212 54.748175,-81.96673 -9.221995,15.79094 -3.917955,18.80285 -3.917955,18.80285 7.337901,-21.96856 13.652749,-30.76839 66.341642,-38.70978 -15.16261,11.41531 -6.45286,41.25445 -50.134453,55.21738 12.683753,-2.73301 25.822443,-8.73747 31.679703,-15.66516 -3.25494,22.40519 -51.89095,60.24666 -84.84585,64.99456 z"
|
||||
id="path872"
|
||||
inkscape:connector-curvature="0"
|
||||
sodipodi:nodetypes="cccccccccc" />
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.4 KiB |
|
|
@ -2,8 +2,21 @@
|
|||
title: Plume documentation
|
||||
---
|
||||
|
||||
<ul>
|
||||
<% sitemap.resources.select{ |p| p.path =~ /\.html/ && p.path != "index.html" }.each do |res| %>
|
||||
<li><a href="<%= res.url %>"><%= res.data.title %></a></li>
|
||||
<h1>Topics</h1>
|
||||
|
||||
<div class="cards">
|
||||
<% sitemap.resources
|
||||
.select{ |p| p.path =~ /\.html/ && p.path != "index.html" && p.url.chomp('/').split('/').size == 2 }
|
||||
.sort{ |a, b| a.data.title <=> b.data.title }
|
||||
.sort{ |a, b| -(a.data.priority || 0) <=> -(b.data.priority || 0) }
|
||||
.each do |res|
|
||||
%>
|
||||
<article>
|
||||
<i data-feather="<%= res.data.icon %>"></i>
|
||||
<h2>
|
||||
<a href="<%= res.url %>"><%= res.data.title %></a>
|
||||
</h2>
|
||||
<p><%= res.data.summary %></p>
|
||||
</article>
|
||||
<% end %>
|
||||
</ul>
|
||||
</div>
|
||||
|
|
@ -1,569 +0,0 @@
|
|||
---
|
||||
title: Installing Plume (for development or production)
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
In order to be installed and to work correctly, Plume needs:
|
||||
|
||||
- *Git* (to get the code)
|
||||
- *Curl* (for RustUp, the Rust installer)
|
||||
- *GCC* and *make* (to compile C dependencies)
|
||||
- *PostgreSQL* or *SQlite 3 development files* (for the database)
|
||||
- *GetText* (to manage translations)
|
||||
- *Rust* and *Cargo* (to build the code)
|
||||
- *OpenSSL* and *OpenSSL librairies* (for security)
|
||||
- *pkg-config* (for openssl-sys compilation)
|
||||
|
||||
All the following instructions will need a terminal.
|
||||
|
||||
Here are the commands to install PostgreSQL and GetText on various operating systems.
|
||||
Some of them may need root permissions.
|
||||
|
||||
You can also install the project using Docker and docker-compose, please refer
|
||||
to the `Docker install` section.
|
||||
|
||||
On **Debian**:
|
||||
|
||||
```bash
|
||||
apt update
|
||||
|
||||
# If you want PostgreSQL
|
||||
apt install gettext postgresql postgresql-contrib libpq-dev git curl gcc make openssl libssl-dev pkg-config
|
||||
|
||||
# If you want SQlite
|
||||
apt install gettext libsqlite3-dev git curl gcc make openssl libssl-dev pkg-config
|
||||
|
||||
```
|
||||
|
||||
On **Fedora**, **CentOS** or **RHEL**:
|
||||
|
||||
```bash
|
||||
# If you want PostgreSQL
|
||||
dnf install postgresql-server postgresql-contrib libpqxx libpqxx-devel git curl gcc make openssl openssl-devel gettext
|
||||
|
||||
# If you want SQLite
|
||||
dnf install libsq3-devel sqlite3 libsqlite3-dev git curl gcc make openssl openssl-devel gettext
|
||||
```
|
||||
|
||||
On **Gentoo**:
|
||||
|
||||
```bash
|
||||
emerge --sync
|
||||
|
||||
# If you want PostgreSQL
|
||||
emerge -avu dev-db/postgresql dev-vcs/git sys-devel/gettext
|
||||
|
||||
# If you want SQlite
|
||||
emerge -avu dev-db/sqlite dev-vcs/git sys-devel/gettext
|
||||
```
|
||||
|
||||
On **Mac OS X**, with [Homebrew](https://brew.sh/):
|
||||
|
||||
```bash
|
||||
brew update
|
||||
|
||||
# For PostgreSQL
|
||||
brew install postgres gettext git
|
||||
|
||||
# For SQlite (already present, so only GetText and Git are needed)
|
||||
brew install gettext git
|
||||
```
|
||||
|
||||
## Configuring PostgreSQL
|
||||
|
||||
You can either run PostgreSQL from the machine that runs Plume, or from another server. We recommend you to use the first setup for development environments, or in production for small instances.
|
||||
|
||||
In the first case, just run this command after the PostgreSQL installation, to start it:
|
||||
|
||||
```
|
||||
service postgresql start
|
||||
```
|
||||
|
||||
If you want to have two separate machines, run these commands on the database server once you've installed the dependencies mentioned above on both servers:
|
||||
|
||||
```bash
|
||||
service postgresql start
|
||||
su - postgres
|
||||
createuser -d -P plume
|
||||
createdb -O plume plume
|
||||
```
|
||||
|
||||
## Creating a new user (optional)
|
||||
|
||||
This step is recommended if you are in a **production environment**, but it is not necessary.
|
||||
|
||||
```bash
|
||||
adduser plume
|
||||
su - plume
|
||||
cd ~
|
||||
```
|
||||
|
||||
Creating a new user will let you use systemd to manage Plume if you want (see the dedicated section below).
|
||||
|
||||
## Installing Rust and Cargo
|
||||
|
||||
We said that Plume needed Rust and Cargo to work, but we didn't install them at the same time as PostgreSQL and GetText, because there is an universal installation method called RustUp.
|
||||
|
||||
You can install it on **GNU/Linux** and **Mac OS X** with:
|
||||
|
||||
```bash
|
||||
curl https://sh.rustup.rs -sSf | sh
|
||||
```
|
||||
|
||||
When asked, choose the *"1) Proceed with installation (default)"* option.
|
||||
|
||||
Then run this command to be able to run cargo in the current session:
|
||||
|
||||
```bash
|
||||
export PATH="$PATH:/home/plume/.cargo/bin:/home/plume/.local/bin:/usr/local/sbin"
|
||||
```
|
||||
|
||||
On **Windows**, you'll need, if you don't already have them, to download and install the [Visual C++ 2015 Build Tools](https://www.microsoft.com/en-us/download/details.aspx?id=48159). Then, download the [rustup installer](https://www.rust-lang.org/en-US/install.html) and run it.
|
||||
|
||||
## Getting Plume's source code
|
||||
|
||||
Plume needs to be compiled from source. To download the code, run:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Plume-org/Plume.git
|
||||
cd Plume
|
||||
|
||||
# If you want PostgreSQL
|
||||
export FEATURES=postgres
|
||||
|
||||
# If you want SQlite
|
||||
export FEATURES=sqlite
|
||||
```
|
||||
|
||||
## Configuring Plume
|
||||
|
||||
Before starting Plume, you'll need to create a configuration file, called `.env`. Here is a sample of what you should put inside.
|
||||
|
||||
```bash
|
||||
# The address of the database
|
||||
# (replace USER, PASSWORD, PORT and DATABASE_NAME with your values)
|
||||
#
|
||||
# If you are using SQlite, use the path of the database file (`plume.db` for instance)
|
||||
DATABASE_URL=postgres://USER:PASSWORD@IP:PORT/DATABASE_NAME
|
||||
|
||||
# For PostgreSQL: migrations/postgres
|
||||
# For SQlite: migrations/sqlite
|
||||
MIGRATION_DIRECTORY=migrations/postgres
|
||||
|
||||
# The domain on which your instance will be available
|
||||
BASE_URL=plu.me
|
||||
|
||||
# Secret key used for private cookies and CSRF protection
|
||||
# You can generate one with `openssl rand -base64 32`
|
||||
ROCKET_SECRET_KEY=
|
||||
```
|
||||
|
||||
For more information about what you can put in your `.env`, see [the documentation about environment variables](/environment).
|
||||
|
||||
## Running migrations
|
||||
|
||||
Migrations are scripts used to update the database. They are run by a tool called Diesel, which can be installed with:
|
||||
|
||||
```bash
|
||||
cargo install diesel_cli --no-default-features --features $FEATURES --version '=1.3.0'
|
||||
```
|
||||
|
||||
To run the migrations, you can do:
|
||||
|
||||
```bash
|
||||
diesel migration run
|
||||
```
|
||||
|
||||
Migrations should be run before using Plume or the `plm` CLI tool, and after each update.
|
||||
When in doubt, run them.
|
||||
|
||||
## Running Plume
|
||||
|
||||
Then, you'll need to install Plume and the CLI tools to manage your instance.
|
||||
|
||||
```
|
||||
# Build the front-end
|
||||
cargo install cargo-web
|
||||
cargo web deploy -p plume-front
|
||||
|
||||
# Build the back-end
|
||||
cargo install --no-default-features --features $FEATURES
|
||||
|
||||
# Build plm, the CLI helper
|
||||
cargo install --no-default-features --features $FEATURES --path plume-cli
|
||||
```
|
||||
|
||||
After that, you'll need to setup your instance, and the admin's account.
|
||||
|
||||
```
|
||||
plm instance new
|
||||
plm users new --admin
|
||||
```
|
||||
|
||||
You will also need to initialise search index
|
||||
|
||||
```
|
||||
plm search init -p path/to/plume/workingdir
|
||||
```
|
||||
|
||||
For more information about these commands, and the arguments you can give them, check out [their documentaion](/CLI).
|
||||
|
||||
Finally, you can start Plume with:
|
||||
|
||||
```bash
|
||||
plume
|
||||
```
|
||||
|
||||
We may provide precompiled packages in the future; if you have experience in these fields and want to help, feel free to discuss this in issues and to propose pull-requests!
|
||||
|
||||
## Docker install
|
||||
|
||||
You can use `docker` and `docker-compose` in order to manage your Plume instance and have it isolated from your host:
|
||||
|
||||
```bash
|
||||
git clone git@github.com:Plume-org/Plume.git
|
||||
cd Plume
|
||||
curl https://docs.joinplu.me/docker-compose.sample.yml > docker-compose.yml
|
||||
curl https://docs.joinplu.me/docker.sample.env > .env
|
||||
|
||||
# Build the containers
|
||||
docker-compose build
|
||||
|
||||
# Launch the database
|
||||
docker-compose up -d postgres
|
||||
# Setup the database (create it and run migrations)
|
||||
docker-compose run --rm plume diesel database setup
|
||||
|
||||
# Setup your instance
|
||||
docker-compose run --rm plume plm instance new
|
||||
docker-compose run --rm plume plm users new --admin
|
||||
docker-compose run --rm plume plm search init
|
||||
|
||||
# Launch your instance for good
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
Then, you can configure your reverse proxy.
|
||||
|
||||
## Configuring Nginx
|
||||
|
||||
Here is a sample Nginx configuration for a Plume instance (replace `blog.example.com` with your domain name):
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
server_name blog.example.com;
|
||||
|
||||
location /.well-known/acme-challenge {}
|
||||
location / {
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
server_name blog.example.org;
|
||||
|
||||
access_log /var/log/nginx/access.log;
|
||||
root /home/plume/Plume/ ;
|
||||
|
||||
SSLCertificateFile /etc/letsencrypt/live/blog.example.com/cert.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/blog.example.com/privkey.pem
|
||||
SSLCertificateChainFile /etc/letsencrypt/live/blog.example.com/chain.pem
|
||||
|
||||
# for ssl conf: https://cipherli.st/
|
||||
ssl_protocols TLSv1.2 TLSv1.3;# Requires nginx >= 1.13.0 else use TLSv1.2
|
||||
ssl_prefer_server_ciphers on;
|
||||
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;# openssl dhparam -out /etc/letsencrypt/ssl-dhparam.pem 4096
|
||||
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384;
|
||||
ssl_ecdh_curve secp384r1; # Requires nginx >= 1.1.0
|
||||
ssl_session_timeout 10m;
|
||||
ssl_session_cache shared:SSL:10m;
|
||||
ssl_session_tickets off; # Requires nginx >= 1.5.9
|
||||
ssl_stapling on; # Requires nginx >= 1.3.7
|
||||
ssl_stapling_verify on; # Requires nginx => 1.3.7
|
||||
resolver 9.9.9.9 80.67.169.12 valid=300s;
|
||||
resolver_timeout 5s;
|
||||
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
|
||||
add_header X-Frame-Options DENY;
|
||||
add_header X-Content-Type-Options nosniff;
|
||||
add_header X-XSS-Protection "1; mode=block";
|
||||
add_header Content-Security-Policy "default-src 'self' 'unsafe-inline'; frame-ancestors 'self'; frame-src https:";
|
||||
|
||||
location ~* \.(jpg|jpeg|png|gif|ico|js|pdf|wasm)$ {
|
||||
add_header Cache-Control "public";
|
||||
expires 7d;
|
||||
}
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:7878/;
|
||||
proxy_set_header Host $http_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;
|
||||
client_max_body_size 10m;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuring Apache
|
||||
|
||||
If you prefer Apache, you can use this configuration (here too, replace `blog.example.com` with your domain):
|
||||
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
ServerName blog.example.com
|
||||
Redirect / https://blog.example.com/
|
||||
</VirtualHost>
|
||||
SSLStaplingCache "shmcb:logs/stapling-cache(150000)"
|
||||
<VirtualHost *:443>
|
||||
ServerAdmin admin@example.com
|
||||
ServerName blog.example.com
|
||||
<Directory "/home/plume/Plume">
|
||||
Header always set Referrer-Policy "strict-origin-when-cross-origin"
|
||||
Header always set Strict-Transport-Security "max-age=31536000"
|
||||
</Directory>
|
||||
SSLEngine on
|
||||
|
||||
# for cipher conf: https://cipherli.st/
|
||||
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
|
||||
SSLProtocol All -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
|
||||
SSLHonorCipherOrder On
|
||||
Header always set Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
|
||||
Header always set X-Frame-Options DENY
|
||||
Header always set X-Content-Type-Options nosniff
|
||||
SSLCompression off
|
||||
SSLUseStapling on
|
||||
|
||||
# Requires Apache >= 2.4.11
|
||||
SSLSessionTickets Off
|
||||
|
||||
SSLCertificateFile /etc/letsencrypt/live/blog.example.com/cert.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/blog.example.com/privkey.pem
|
||||
SSLCertificateChainFile /etc/letsencrypt/live/blog.example.com/chain.pem
|
||||
|
||||
ProxyPreserveHost On
|
||||
RequestHeader set X-Forwarded-Proto "https"
|
||||
|
||||
ProxyPass / http://127.0.0.1:7878/
|
||||
ProxyPassReverse / http://127.0.0.1:7878/
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
## Configuring Caddyserver
|
||||
|
||||
If you prefer [Caddyserver](http://caddyserver.com), you can use this configuration (again, replacing `blog.example.com` with your domain):
|
||||
|
||||
```
|
||||
blog.example.com {
|
||||
proxy / localhost:7878 {
|
||||
transparent
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Systemd integration
|
||||
|
||||
If you want to manage your Plume instance with systemd, you can use the following unit file (to be saved in `/etc/systemd/system/plume.service`):
|
||||
|
||||
```toml
|
||||
[Unit]
|
||||
Description=plume
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=plume
|
||||
WorkingDirectory=/home/plume/Plume
|
||||
ExecStart=/home/plume/.cargo/bin/plume
|
||||
TimeoutSec=30
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Now you need to enable all of these services:
|
||||
|
||||
```bash
|
||||
systemctl enable /etc/systemd/system/plume.service
|
||||
```
|
||||
|
||||
Now start the services:
|
||||
|
||||
```bash
|
||||
systemctl start plume.service
|
||||
```
|
||||
|
||||
Check that they are properly running:
|
||||
|
||||
```bash
|
||||
systemctl status plume.service
|
||||
```
|
||||
|
||||
## SysVinit integration
|
||||
|
||||
This script can also be useful if you are using SysVinit.
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
### BEGIN INIT INFO
|
||||
# Provides:
|
||||
# Required-Start: $remote_fs $syslog
|
||||
# Required-Stop: $remote_fs $syslog
|
||||
# Default-Start: 2 3 4 5
|
||||
# Default-Stop: 0 1 6
|
||||
# Short-Description: Start daemon at boot time
|
||||
# Description: Federated blogging
|
||||
# Based on https://raw.githubusercontent.com/fhd/init-script-template/master/template
|
||||
### END INIT INFO
|
||||
|
||||
dir="/home/plume/Plume"
|
||||
cmd="/home/plume/.cargo/bin/plume"
|
||||
user="plume"
|
||||
|
||||
name=`basename $0`
|
||||
pid_file="/var/run/$name.pid"
|
||||
stdout_log="/home/plume/Plume/plume.log"
|
||||
stderr_log="/home/plume/Plume/plume.err"
|
||||
|
||||
get_pid() {
|
||||
cat "$pid_file"
|
||||
}
|
||||
|
||||
is_running() {
|
||||
[ -f "$pid_file" ] && ps -p `get_pid` > /dev/null 2>&1
|
||||
}
|
||||
|
||||
case "$1" in
|
||||
start)
|
||||
if is_running; then
|
||||
echo "Already started"
|
||||
else
|
||||
echo "Starting $name"
|
||||
cd "$dir"
|
||||
if [ -z "$user" ]; then
|
||||
sudo $cmd >> "$stdout_log" 2>> "$stderr_log" &
|
||||
else
|
||||
sudo -u "$user" $cmd >> "$stdout_log" 2>> "$stderr_log" &
|
||||
fi
|
||||
echo $! > "$pid_file"
|
||||
if ! is_running; then
|
||||
echo "Unable to start, see $stdout_log and $stderr_log"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
;;
|
||||
stop)
|
||||
if is_running; then
|
||||
echo -n "Stopping $name.."
|
||||
kill `get_pid`
|
||||
for i in 1 2 3 4 5 6 7 8 9 10
|
||||
# for i in `seq 10`
|
||||
do
|
||||
if ! is_running; then
|
||||
break
|
||||
fi
|
||||
|
||||
echo -n "."
|
||||
sleep 1
|
||||
done
|
||||
echo
|
||||
|
||||
if is_running; then
|
||||
echo "Not stopped; may still be shutting down or shutdown may have failed"
|
||||
exit 1
|
||||
else
|
||||
echo "Stopped"
|
||||
if [ -f "$pid_file" ]; then
|
||||
rm "$pid_file"
|
||||
fi
|
||||
fi
|
||||
else
|
||||
echo "Not running"
|
||||
fi
|
||||
;;
|
||||
restart)
|
||||
$0 stop
|
||||
if is_running; then
|
||||
echo "Unable to stop, will not attempt to start"
|
||||
exit 1
|
||||
fi
|
||||
$0 start
|
||||
;;
|
||||
status)
|
||||
if is_running; then
|
||||
echo "Running"
|
||||
else
|
||||
echo "Stopped"
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
*)
|
||||
echo "Usage: $0 {start|stop|restart|status}"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
exit 0
|
||||
|
||||
```
|
||||
|
||||
Now start the services:
|
||||
|
||||
```bash
|
||||
service plume.service start
|
||||
```
|
||||
|
||||
|
||||
And check:
|
||||
|
||||
```bash
|
||||
service plume.service status
|
||||
```
|
||||
|
||||
## OpenRC integration
|
||||
|
||||
This script can also be useful if you are using OpenRC.
|
||||
|
||||
```bash
|
||||
#! /sbin/openrc-run
|
||||
name="plume"
|
||||
description="plume : federated blogging"
|
||||
pidfile=/run/plume
|
||||
start() {
|
||||
ebegin "Starting plume"
|
||||
start-stop-daemon -v --start --exec "/home/plume/.cargo/bin/cargo run" --user "plume" --chdir "/home/plume/Plume" --background --stdout "/var/log/plume.log" --stderr "/var/log/plume.err" --make-pidfile --pidfile "/run/plume" -- "phx.server"
|
||||
eend $?
|
||||
}
|
||||
|
||||
stop() {
|
||||
ebegin "Stopping plume"
|
||||
start-stop-daemon --stop --user "plume" --chdir "/home/plume/Plume" --pidfile "/run/plume"
|
||||
eend $?
|
||||
}
|
||||
```
|
||||
Now you need to enable all of these services:
|
||||
|
||||
```bash
|
||||
rc-update add plume
|
||||
```
|
||||
|
||||
Now start the services:
|
||||
|
||||
```bash
|
||||
/etc/init.d/plume start
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Caveats:
|
||||
|
||||
- Pgbouncer is not supported yet (named transactions are used).
|
||||
- Rust nightly is a moving target, dependancies can break and sometimes you need to check a few versions to find the one working (run `rustup override set nightly-2018-12-06` in the Plume directory if you have issues during the compilation)
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
Most of this documentation has been written by *gled-rs*. The systemd unit file, Nginx and Apache configurations have been written by *nonbinaryanargeek*. Some parts (especially the instructions to install native dependencies) are from the [Aardwolf project](https://github.com/Aardwolf-Social/aardwolf). The docker instructions, and files have been added by *Eliot Berriot*.
|
||||
68
source/installation/config.html.md
Normal file
68
source/installation/config.html.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: Configuring Plume
|
||||
---
|
||||
|
||||
If you are using PostgreSQL, you have to create a database for Plume.
|
||||
|
||||
```
|
||||
service postgresql start
|
||||
su - postgres
|
||||
createuser -d -P plume
|
||||
createdb -O plume plume
|
||||
```
|
||||
|
||||
Before starting Plume, you'll need to create a configuration file, called `.env`.
|
||||
Here is a sample of what you should put inside.
|
||||
|
||||
```bash
|
||||
# The address of the database
|
||||
# (replace USER, PASSWORD, PORT and DATABASE_NAME with your values)
|
||||
#
|
||||
# If you are using SQlite, use the path of the database file (`plume.db` for instance)
|
||||
DATABASE_URL=postgres://USER:PASSWORD@IP:PORT/DATABASE_NAME
|
||||
|
||||
# For PostgreSQL: migrations/postgres
|
||||
# For SQlite: migrations/sqlite
|
||||
MIGRATION_DIRECTORY=migrations/postgres
|
||||
|
||||
# The domain on which your instance will be available
|
||||
BASE_URL=plu.me
|
||||
|
||||
# Secret key used for private cookies and CSRF protection
|
||||
# You can generate one with `openssl rand -base64 32`
|
||||
ROCKET_SECRET_KEY=
|
||||
```
|
||||
|
||||
For more information about what you can put in your `.env`,
|
||||
see [the documentation about environment variables](/environment).
|
||||
|
||||
Now we need to run migrations. Migrations are scripts used to update
|
||||
the database. They are run by `diesel` that we previously installed.
|
||||
To run the migrations, you can do:
|
||||
|
||||
```bash
|
||||
diesel migration run
|
||||
```
|
||||
|
||||
Migrations should be run after each update. When in doubt, run them.
|
||||
|
||||
After that, you'll need to setup your instance, and the admin's account.
|
||||
|
||||
```
|
||||
plm instance new
|
||||
plm users new --admin
|
||||
```
|
||||
|
||||
You will also need to initialise search index
|
||||
|
||||
```
|
||||
plm search init
|
||||
```
|
||||
|
||||
For more information about these commands, and the arguments you can give them,
|
||||
check out [their documentaion](/CLI).
|
||||
|
||||
Now that Plume is configured, if you are in a production environment you probably
|
||||
want to configure your init system to make it easier to manage.
|
||||
|
||||
<a class="action" href="/installation/init">Configure init system</a>
|
||||
33
source/installation/deps.html.md
Normal file
33
source/installation/deps.html.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: Installing native dependencies
|
||||
---
|
||||
|
||||
In order to be installed and to work correctly, Plume needs:
|
||||
|
||||
- *Git* (to get the code)
|
||||
- *Curl* (for RustUp, the Rust installer)
|
||||
- *GCC* and *make* (to compile C dependencies)
|
||||
- *PostgreSQL* or *SQlite 3 development files* (for the database)
|
||||
- *GetText* (to manage translations)
|
||||
- *Rust* and *Cargo* (to build the code)
|
||||
- *OpenSSL* and *OpenSSL librairies* (for security)
|
||||
- *pkg-config* (for openssl-sys compilation)
|
||||
|
||||
Depending on your operating system, the commands to get all these dependencies
|
||||
are not the same, so we need to know what is installed on your machine to guide
|
||||
you:
|
||||
|
||||
<ul class="choices">
|
||||
<li><a href="/installation/deps/deb">
|
||||
Debian, Ubuntu or another Linux ditribution based on DEB
|
||||
</a></li>
|
||||
<li><a href="/installation/deps/rpm">
|
||||
Fedora, RHEL, CentOS or another Linux ditribution based on DEB
|
||||
</a></li>
|
||||
<li><a href="/installation/deps/gentoo">
|
||||
Gentoo
|
||||
</a></li>
|
||||
<li><a href="/installation/deps/macosx">
|
||||
Mac OS X
|
||||
</a></li>
|
||||
</ul>
|
||||
30
source/installation/deps/deb.html.md
Normal file
30
source/installation/deps/deb.html.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: Dependencies on Debian & Co
|
||||
---
|
||||
|
||||
First, make sure your computer is aware of the latest availabel versions of installable
|
||||
packages. This command, and the other on this page, may require super-user rights, so
|
||||
you may want to prefix them by `sudo`.
|
||||
|
||||
```bash
|
||||
apt update
|
||||
```
|
||||
|
||||
Then, the command to actually install dependencies depends on the database backend you
|
||||
want to use.
|
||||
|
||||
If you want **PostgreSQL**, use:
|
||||
|
||||
```
|
||||
apt install postgresql postgresql-contrib libpq-dev gettext git curl gcc make openssl libssl-dev pkg-config
|
||||
```
|
||||
|
||||
If you prefer to use **SQlite**:
|
||||
|
||||
```
|
||||
apt install libsqlite3-dev gettext git curl gcc make openssl libssl-dev pkg-config
|
||||
```
|
||||
|
||||
Now that these dependencies have been installed, we need to install Rust which has a special installer.
|
||||
|
||||
<a class="action" href="/installation/deps/rust">Let's do it!</a>
|
||||
17
source/installation/deps/gentoo.html.md
Normal file
17
source/installation/deps/gentoo.html.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Dependencies on Gentoo
|
||||
---
|
||||
|
||||
```bash
|
||||
emerge --sync
|
||||
|
||||
# If you want PostgreSQL
|
||||
emerge -avu dev-db/postgresql dev-vcs/git sys-devel/gettext
|
||||
|
||||
# If you want SQlite
|
||||
emerge -avu dev-db/sqlite dev-vcs/git sys-devel/gettext
|
||||
```
|
||||
|
||||
Now that these dependencies have been installed, we need to install Rust which has a special installer.
|
||||
|
||||
<a class="action" href="/installation/deps/rust">Let's do it!</a>
|
||||
19
source/installation/deps/macosx.html.md
Normal file
19
source/installation/deps/macosx.html.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: Installing dependencies on Mac OS X
|
||||
---
|
||||
|
||||
With [Homebrew](https://brew.sh/):
|
||||
|
||||
```bash
|
||||
brew update
|
||||
|
||||
# For PostgreSQL
|
||||
brew install postgres gettext git
|
||||
|
||||
# For SQlite (already present, so only GetText and Git are needed)
|
||||
brew install gettext git
|
||||
```
|
||||
|
||||
Now that these dependencies have been installed, we need to install Rust which has a special installer.
|
||||
|
||||
<a class="action" href="/installation/deps/rust">Let's do it!</a>
|
||||
15
source/installation/deps/rpm.html.md
Normal file
15
source/installation/deps/rpm.html.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: Installing dependencies on RPM-based systems
|
||||
---
|
||||
|
||||
```bash
|
||||
# If you want PostgreSQL
|
||||
dnf install postgresql-server postgresql-contrib libpqxx libpqxx-devel git curl gcc make openssl openssl-devel gettext
|
||||
|
||||
# If you want SQLite
|
||||
dnf install libsq3-devel sqlite3 libsqlite3-dev git curl gcc make openssl openssl-devel gettext
|
||||
```
|
||||
|
||||
Now that these dependencies have been installed, we need to install Rust which has a special installer.
|
||||
|
||||
<a class="action" href="/installation/deps/rust">Let's do it!</a>
|
||||
44
source/installation/deps/rust.html.md
Normal file
44
source/installation/deps/rust.html.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Installing Rust & Cargo
|
||||
---
|
||||
|
||||
TODO: instructions to choose the correct nightly directly?
|
||||
|
||||
Rust and Cargo use a special installer called *RustUp* that let's you manage
|
||||
various versions of these two programs in parallel.
|
||||
|
||||
You can eventually create a specific user for your Rust and Plume installations, to
|
||||
isolate them from the rest of your system. This step is recommended if you are in
|
||||
a **production environment**, but it is not necessary.
|
||||
|
||||
```bash
|
||||
adduser plume
|
||||
su - plume
|
||||
cd ~
|
||||
```
|
||||
|
||||
You can now install RustUp on **GNU/Linux** and **Mac OS X** with:
|
||||
|
||||
```bash
|
||||
curl https://sh.rustup.rs -sSf | sh
|
||||
```
|
||||
|
||||
When asked, choose the *"1) Proceed with installation (default)"* option.
|
||||
|
||||
Then run this command to be able to run cargo in the current session:
|
||||
|
||||
```bash
|
||||
export PATH="$PATH:/home/plume/.cargo/bin:/home/plume/.local/bin:/usr/local/sbin"
|
||||
```
|
||||
|
||||
On **Windows**, you'll need, if you don't already have them, to download and
|
||||
install the [Visual C++ 2015 Build Tools](https://www.microsoft.com/en-us/download/details.aspx?id=48159).
|
||||
Then, download the [rustup installer](https://www.rust-lang.org/en-US/install.html)
|
||||
and run it.
|
||||
|
||||
You can check that everything is correctly installed with `rustc --version` and
|
||||
`cargo --version`.
|
||||
|
||||
We can now compile Plume's source code.
|
||||
|
||||
<a class="action" href="/installation/with/source-code">Compiling Plume</a>
|
||||
17
source/installation/index.html.md
Normal file
17
source/installation/index.html.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Installing Plume
|
||||
icon: package
|
||||
summary: 'A guide to install your own Plume instance, using various methods (Docker, YunoHost, from source, etc)'
|
||||
priority: 3
|
||||
---
|
||||
|
||||
There are various ways to install Plume. Please, choose the one that suits you the best
|
||||
in this list:
|
||||
|
||||
<ul class="choices">
|
||||
<li><a href="with/docker">Docker</a></li>
|
||||
<li><a href="with/yunohost">YunoHost (not documented yet)</a></li>
|
||||
<li><a href="with/lollipop">Lollipop Cloud (not documented yet)</a></li>
|
||||
<li><a href="deps/prebuilt">Prebuilt binaries (not available yet)</a></li>
|
||||
<li><a href="deps">From source</a></li>
|
||||
</ul>
|
||||
24
source/installation/init.html.md
Normal file
24
source/installation/init.html.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
title: Choose your init system
|
||||
---
|
||||
|
||||
The init system is the first program to start when a computer boots. Its role is
|
||||
to start other program automatically and to let you manage them more easily.
|
||||
|
||||
<ul class="choices">
|
||||
<li><a href="/installation/init/systemd">SystemD</a></li>
|
||||
<li><a href="/installation/init/sysvinit">SysVInit</a></li>
|
||||
<li><a href="/installation/init/openrc">OpenRC</a></li>
|
||||
</ul>
|
||||
|
||||
# How to know which init system I have?
|
||||
|
||||
You can use this little script.
|
||||
|
||||
```bash
|
||||
if [[ `systemctl` =~ -\.mount ]]; then echo "SystemD";
|
||||
elif [[ -f /etc/init.d/cron && ! -h /etc/init.d/cron ]]; then echo using "SysVInit";
|
||||
else echo "Can't tell"; fi
|
||||
```
|
||||
|
||||
[(Found here)](https://unix.stackexchange.com/a/164092)
|
||||
39
source/installation/init/openrc.html.md
Normal file
39
source/installation/init/openrc.html.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: Configuring OpenRC
|
||||
---
|
||||
|
||||
This script can also be useful if you are using OpenRC.
|
||||
|
||||
```bash
|
||||
#! /sbin/openrc-run
|
||||
name="plume"
|
||||
description="plume : federated blogging"
|
||||
pidfile=/run/plume
|
||||
start() {
|
||||
ebegin "Starting plume"
|
||||
start-stop-daemon -v --start --exec "/home/plume/.cargo/bin/cargo run" --user "plume" --chdir "/home/plume/Plume" --background --stdout "/var/log/plume.log" --stderr "/var/log/plume.err" --make-pidfile --pidfile "/run/plume" -- "phx.server"
|
||||
eend $?
|
||||
}
|
||||
|
||||
stop() {
|
||||
ebegin "Stopping plume"
|
||||
start-stop-daemon --stop --user "plume" --chdir "/home/plume/Plume" --pidfile "/run/plume"
|
||||
eend $?
|
||||
}
|
||||
```
|
||||
Now you need to enable all of these services:
|
||||
|
||||
```bash
|
||||
rc-update add plume
|
||||
```
|
||||
|
||||
Now start the services:
|
||||
|
||||
```bash
|
||||
/etc/init.d/plume start
|
||||
```
|
||||
|
||||
If everything works fine, the last step before you can use your Plume instance
|
||||
is to configure a reverse-proxy.
|
||||
|
||||
<a class="action" href="/installation/proxy">Reverse-proxy configuration</a>
|
||||
45
source/installation/init/systemd.html.md
Normal file
45
source/installation/init/systemd.html.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: Configuring SystemD
|
||||
---
|
||||
|
||||
If you want to manage your Plume instance with systemd, you can use the following
|
||||
unit file (to be saved in `/etc/systemd/system/plume.service`):
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=plume
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=plume
|
||||
WorkingDirectory=/home/plume/Plume
|
||||
ExecStart=/home/plume/.cargo/bin/plume
|
||||
TimeoutSec=30
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Now you need to enable all of these services:
|
||||
|
||||
```bash
|
||||
systemctl enable /etc/systemd/system/plume.service
|
||||
```
|
||||
|
||||
Now start the services:
|
||||
|
||||
```bash
|
||||
systemctl start plume.service
|
||||
```
|
||||
|
||||
Check that they are properly running:
|
||||
|
||||
```bash
|
||||
systemctl status plume.service
|
||||
```
|
||||
|
||||
If everything works fine, the last step before you can use your Plume instance
|
||||
is to configure a reverse-proxy.
|
||||
|
||||
<a class="action" href="/installation/proxy">Reverse-proxy configuration</a>
|
||||
127
source/installation/init/sysvinit.html.md
Normal file
127
source/installation/init/sysvinit.html.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
title: Configuring SysVInit
|
||||
---
|
||||
|
||||
This script can also be useful if you are using SysVinit.
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
### BEGIN INIT INFO
|
||||
# Provides:
|
||||
# Required-Start: $remote_fs $syslog
|
||||
# Required-Stop: $remote_fs $syslog
|
||||
# Default-Start: 2 3 4 5
|
||||
# Default-Stop: 0 1 6
|
||||
# Short-Description: Start daemon at boot time
|
||||
# Description: Federated blogging
|
||||
# Based on https://raw.githubusercontent.com/fhd/init-script-template/master/template
|
||||
### END INIT INFO
|
||||
|
||||
dir="/home/plume/Plume"
|
||||
cmd="/home/plume/.cargo/bin/plume"
|
||||
user="plume"
|
||||
|
||||
name=`basename $0`
|
||||
pid_file="/var/run/$name.pid"
|
||||
stdout_log="/home/plume/Plume/plume.log"
|
||||
stderr_log="/home/plume/Plume/plume.err"
|
||||
|
||||
get_pid() {
|
||||
cat "$pid_file"
|
||||
}
|
||||
|
||||
is_running() {
|
||||
[ -f "$pid_file" ] && ps -p `get_pid` > /dev/null 2>&1
|
||||
}
|
||||
|
||||
case "$1" in
|
||||
start)
|
||||
if is_running; then
|
||||
echo "Already started"
|
||||
else
|
||||
echo "Starting $name"
|
||||
cd "$dir"
|
||||
if [ -z "$user" ]; then
|
||||
sudo $cmd >> "$stdout_log" 2>> "$stderr_log" &
|
||||
else
|
||||
sudo -u "$user" $cmd >> "$stdout_log" 2>> "$stderr_log" &
|
||||
fi
|
||||
echo $! > "$pid_file"
|
||||
if ! is_running; then
|
||||
echo "Unable to start, see $stdout_log and $stderr_log"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
;;
|
||||
stop)
|
||||
if is_running; then
|
||||
echo -n "Stopping $name.."
|
||||
kill `get_pid`
|
||||
for i in 1 2 3 4 5 6 7 8 9 10
|
||||
# for i in `seq 10`
|
||||
do
|
||||
if ! is_running; then
|
||||
break
|
||||
fi
|
||||
|
||||
echo -n "."
|
||||
sleep 1
|
||||
done
|
||||
echo
|
||||
|
||||
if is_running; then
|
||||
echo "Not stopped; may still be shutting down or shutdown may have failed"
|
||||
exit 1
|
||||
else
|
||||
echo "Stopped"
|
||||
if [ -f "$pid_file" ]; then
|
||||
rm "$pid_file"
|
||||
fi
|
||||
fi
|
||||
else
|
||||
echo "Not running"
|
||||
fi
|
||||
;;
|
||||
restart)
|
||||
$0 stop
|
||||
if is_running; then
|
||||
echo "Unable to stop, will not attempt to start"
|
||||
exit 1
|
||||
fi
|
||||
$0 start
|
||||
;;
|
||||
status)
|
||||
if is_running; then
|
||||
echo "Running"
|
||||
else
|
||||
echo "Stopped"
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
*)
|
||||
echo "Usage: $0 {start|stop|restart|status}"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
exit 0
|
||||
|
||||
```
|
||||
|
||||
Now start the services:
|
||||
|
||||
```bash
|
||||
service plume.service start
|
||||
```
|
||||
|
||||
|
||||
And check:
|
||||
|
||||
```bash
|
||||
service plume.service status
|
||||
```
|
||||
|
||||
If everything works fine, the last step before you can use your Plume instance
|
||||
is to configure a reverse-proxy.
|
||||
|
||||
<a class="action" href="/installation/proxy">Reverse-proxy configuration</a>
|
||||
26
source/installation/proxy.html.md
Normal file
26
source/installation/proxy.html.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: Choose your reverse proxy
|
||||
---
|
||||
|
||||
The reverse-proxy is the program in charge of redirecting requests on your server
|
||||
to your Plume instance. It is especially useful if you have other services running
|
||||
on the same machine, so that people are redirected to the correct one. Please choose
|
||||
your reverse proxy in this list:
|
||||
|
||||
<ul class="choices">
|
||||
<li><a href="proxy/caddy">Caddy</a></li>
|
||||
<li><a href="proxy/nginx">Nginx</a></li>
|
||||
<li><a href="proxy/apache">Apache</a></li>
|
||||
<li><a href="proxy/none">No reverse-proxy</a></li>
|
||||
</ul>
|
||||
|
||||
If you don't have a reverse-proxy on your server yet but want one, we recommend
|
||||
Caddy as the configuration is really simple.
|
||||
|
||||
# How to know which reverse proxy I have?
|
||||
|
||||
This command should give you (most of the time) what your reverse-proxy is.
|
||||
|
||||
```bash
|
||||
sudo netstat -tlnup | grep :80
|
||||
```
|
||||
47
source/installation/proxy/apache.html.md
Normal file
47
source/installation/proxy/apache.html.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
title: Configuring Apache
|
||||
---
|
||||
|
||||
If you prefer Apache, you can use this configuration (replace `DOMAIN_NAME` with your domain):
|
||||
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
ServerName DOMAIN_NAME
|
||||
Redirect / https://DOMAIN_NAME/
|
||||
</VirtualHost>
|
||||
SSLStaplingCache "shmcb:logs/stapling-cache(150000)"
|
||||
<VirtualHost *:443>
|
||||
ServerAdmin admin@example.com
|
||||
ServerName DOMAIN_NAME
|
||||
<Directory "/home/plume/Plume">
|
||||
Header always set Referrer-Policy "strict-origin-when-cross-origin"
|
||||
Header always set Strict-Transport-Security "max-age=31536000"
|
||||
</Directory>
|
||||
SSLEngine on
|
||||
|
||||
# for cipher conf: https://cipherli.st/
|
||||
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
|
||||
SSLProtocol All -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
|
||||
SSLHonorCipherOrder On
|
||||
Header always set Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
|
||||
Header always set X-Frame-Options DENY
|
||||
Header always set X-Content-Type-Options nosniff
|
||||
SSLCompression off
|
||||
SSLUseStapling on
|
||||
|
||||
# Requires Apache >= 2.4.11
|
||||
SSLSessionTickets Off
|
||||
|
||||
SSLCertificateFile /etc/letsencrypt/live/DOMAIN_NAME/cert.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/DOMAIN_NAME/privkey.pem
|
||||
SSLCertificateChainFile /etc/letsencrypt/live/DOMAIN_NAME/chain.pem
|
||||
|
||||
ProxyPreserveHost On
|
||||
RequestHeader set X-Forwarded-Proto "https"
|
||||
|
||||
ProxyPass / http://127.0.0.1:7878/
|
||||
ProxyPassReverse / http://127.0.0.1:7878/
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
Restart Apache, and your Plume instance should be accessible!
|
||||
17
source/installation/proxy/caddy.html.md
Normal file
17
source/installation/proxy/caddy.html.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Configuring Caddy
|
||||
---
|
||||
|
||||
The Caddy configuration is very short.
|
||||
|
||||
```
|
||||
DOMAIN_NAME {
|
||||
proxy / localhost:7878 {
|
||||
transparent
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Don't forget to replace `DOMAIN_NAME` with your own domain.
|
||||
|
||||
Restart Caddy, and your Plume instance should be accessible!
|
||||
66
source/installation/proxy/nginx.html.md
Normal file
66
source/installation/proxy/nginx.html.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
title: Configuring Nginx
|
||||
---
|
||||
|
||||
Here is a sample Nginx configuration for a Plume instance (replace `DOMAIN_NAME` with your domain name):
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
server_name DOMAIN_NAME;
|
||||
|
||||
location /.well-known/acme-challenge {}
|
||||
location / {
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
server_name DOMAIN_NAME;
|
||||
|
||||
access_log /var/log/nginx/access.log;
|
||||
root /home/plume/Plume/ ;
|
||||
|
||||
SSLCertificateFile /etc/letsencrypt/live/DOMAIN_NAME/cert.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/DOMAIN_NAME/privkey.pem
|
||||
SSLCertificateChainFile /etc/letsencrypt/live/DOMAIN_NAME/chain.pem
|
||||
|
||||
# for ssl conf: https://cipherli.st/
|
||||
ssl_protocols TLSv1.2 TLSv1.3;# Requires nginx >= 1.13.0 else use TLSv1.2
|
||||
ssl_prefer_server_ciphers on;
|
||||
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;# openssl dhparam -out /etc/letsencrypt/ssl-dhparam.pem 4096
|
||||
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384;
|
||||
ssl_ecdh_curve secp384r1; # Requires nginx >= 1.1.0
|
||||
ssl_session_timeout 10m;
|
||||
ssl_session_cache shared:SSL:10m;
|
||||
ssl_session_tickets off; # Requires nginx >= 1.5.9
|
||||
ssl_stapling on; # Requires nginx >= 1.3.7
|
||||
ssl_stapling_verify on; # Requires nginx => 1.3.7
|
||||
resolver 9.9.9.9 80.67.169.12 valid=300s;
|
||||
resolver_timeout 5s;
|
||||
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
|
||||
add_header X-Frame-Options DENY;
|
||||
add_header X-Content-Type-Options nosniff;
|
||||
add_header X-XSS-Protection "1; mode=block";
|
||||
add_header Content-Security-Policy "default-src 'self' 'unsafe-inline'; frame-ancestors 'self'; frame-src https:";
|
||||
|
||||
location ~* \.(jpg|jpeg|png|gif|ico|js|pdf|wasm)$ {
|
||||
add_header Cache-Control "public";
|
||||
expires 7d;
|
||||
}
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:7878/;
|
||||
proxy_set_header Host $http_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;
|
||||
client_max_body_size 10m;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Restart Nginx, and your Plume instance should be accessible!
|
||||