aitzol/Plume
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up installation docs

Browse Source
This commit is contained in:
Bat 2018-09-01 12:53:14 +01:00
parent 62d299bd7e
commit 44ac96b314
3 changed files with 160 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
docs/DEVELOPMENT.md
View File

@ -1,74 +1,10 @@
# Development Guide # Development Guide
## Running Plume locally ## Installing the development environment
### Mac OSX Please refer to the [installation guide](INSTALL.md).
All commands are run in the Mac Terminal or terminal emulator of your choice, such as iTerm2. First, you will need [Git](https://git-scm.com/download/mac), [Homebrew](https://brew.sh/), [Rust](https://www.rust-lang.org/en-US/), and [Postgres](https://www.postgresql.org/). Follow the instructions to install Homebrew before continuing if you don't already have it. ## Testing the federation
### Linux
Similar to Mac OSX all commands should be run from a terminal (a.k.a command line). First, you will need [Git](https://git-scm.com/download/mac), [Rust](https://www.rust-lang.org/en-US/), and [Postgres](https://www.postgresql.org/). Step-by-step instructions are also available here: [Installing Prerequisites](/doc/PREREQUISITES.md)
#### Download the Repository
Navigate to the directory on your machine where you would like to install the repository, such as in `~/dev` by running `cd dev`. Now, clone the remote repository by running `git clone https://github.com/Plume-org/Plume.git`. This will install the codebase to the `Plume` subdirectory. Navigate into that directory by running `cd Plume`.
#### Rust
If you think you might already have rust on your machine, you can check by running
```
rustc --version
# Should output something like
# rustc 1.28.0-nightly (a805a2a5e 2018-06-10)
```
If you don't already have Rust, install it by running
```
curl https://sh.rustup.rs -sSf | sh
```
In the interactive installation, choose the option of the nightly toolchain. Restart your console so that the `rustc` CLI tool is available.
#### Postgres
Now we will use Homebrew to install Postgres. If you think you might already have it, try running `brew info postgres`. If it is not available, continue to install Postgres by running the following:
```
brew install postgres
```
Now, you can use the following command to start Postgres on a one-time basis.
```
pg_ctl -D /usr/local/var/postgres start
```
When you will launch Plume for the first time, it will setup the database by itself.
#### Database Migration
To run migrations and correctly setup the database, Plume use the `diesel` CLI tool under the hood. Therefore you should install it before running Plume. If this was your time installing Rust, you will probably need to run that using `cargo`. `cargo` is installed with `rustc` so if you followed the earlier instructions it will already be available.
```
cargo install diesel_cli --version '=1.2.0'
```
#### Running Plume
To run Plume locally, make sure you are once again in the Plume directory, such as `~/dev/Plume`. Now you will be able to run the application using the command
```
cargo run
```
#### Configuration
The first time you'll run Plume, it will help you setup your instance through an interactive tool. Once you'll have answered all its question, your instance will start.
#### Testing the federation
To test the federation, you'll need to setup another database (see "Setup the database"), 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 also owned by the "plume" user, but with a different name. Then, you'll need to run the
@ -93,7 +29,7 @@ If you don't want to setup HTTPS locally, you can also disable it by running you
USE_HTTPS=0 cargo run USE_HTTPS=0 cargo run
``` ```
#### Making a Pull Request ## 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. 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.
``` ```
@ -105,7 +41,7 @@ Now, make any changes to the code you want. After committing your changes, push
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. 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.
#### When working with Tera templates ## When working with Tera templates
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: 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:

184
docs/INSTALL.md
View File

@ -1,32 +1,100 @@
# How to install Plume on a Debian stretch: # Installing Plume (for development or production)
## Basic setup: ## Prerequisites
In order to be installed and to work correctly, Plume needs:
- Git
- PostgreSQL
- GetText
- Rust and Cargo
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.
On **Debian**:
```bash ```bash
apt update apt update
apt install gettext postgresql postgresql-contrib libpq-dev apt install gettext postgresql postgresql-contrib libpq-dev git
adduser plume
su - plume
cd /home/plume
git clone https://github.com/Plume-org/Plume.git
curl https://sh.rustup.rs -sSf | sh
cd Plume
rustup toolchain install nightly
rustup toolchain default nightly
rustup update
cargo install diesel_cli --no-default-features --features postgres --version '=1.2.0' # we dont need to compile anything else than pgsql
``` ```
## Now, if you want to run postgresql on the same server: On **Fedora**, **CentOS** or **RHEL**:
```bash ```bash
service postgresql start dnf install postgresql-server postgresql-contrib mariadb-devel libsq3-devel libpqxx libpqxx-devel
cargo run # this will configure and launch Plume on the server. # TODO: GetText + Git install
``` ```
## If you want to run Plume with a remote DB this time ( Postgresql is not installed on the same server/container): On **Gentoo**:
* On the DB server: ```bash
emerge --sync
emerge -av postgresql eselect-postgresql
# TODO: GetText + Git install
```
On **Mac OS X**, with [Homebrew](https://brew.sh/):
```bash
brew update
brew install postgres
# TODO: GetText + Git install
```
## 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 installed 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
```
On **Windows**, you'll need, if you don't already have them, to download and install the [Visual C++ 2015 Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools). Then, download the [rustup installer](https://www.rust-lang.org/en-US/install.html) and run it.
## Getting and compiling the Plume source code
Plume needs to be compiled from source.
```bash
git clone https://github.com/Plume-org/Plume.git
cd Plume
# This may take some time as RustUp will download all
# the required Rust components, and Cargo will download
# and compile all dependencies.
cargo build
```
We may provide precompiled packages and Docker images in the future (if you have experience in these fields and want to help, you're welcome).
## 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 after you installed the dependencies mentionned above on both servers:
```bash ```bash
service postgresql start service postgresql start
@ -35,38 +103,80 @@ createuser -d -P plume
createdb -O plume plume createdb -O plume plume
``` ```
* On the Plume server:
```bash ```bash
cd /home/plume/Plume
diesel migration run --database-url postgres://plume:PASSWORD@DBSERVERIP:DBPORT/plume
DB_URL=postgres://plume:PASSWORD@DBSERVERIP:DBPORT/plume cargo run # the first launch will ask questions to configure the instance. A second launch will not need the DB_URL.
``` ```
## Plume is now accessible as seen on your console. You can have fun now, or configure an nginx proxy with the following excerpt: ## Running migrations
Migrations are scripts 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 postgres --version '=1.2.0'
```
Plume should normally run migrations for you when needed, but if you want to run them manually, the command is:
```bash
diesel migration run --database-url postgres://USER:PASSWORD@IP:PORT/plume
```
This command may be useful if you decided to use a separate database server.
## Starting Plume
When you launch Plume for the first time, it will ask you a few questions to setup your instance before it actually launches. To start it, run these commands.
```
# Optional, only do it if the database URL is not
# postgres://plume:plume@localhost/plume
export DB_URL=postgres://plume:PASSWORD@DBSERVERIP:DBPORT/plume
cargo run
```
## Configuring Nginx
Here is a sample Nginx configuration for a Plume instance:
```nginx
location / { location / {
proxy_http_version 1.1; proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade; proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade"; proxy_set_header Connection "upgrade";
proxy_set_header Host $http_host; proxy_set_header Host $http_host;
proxy_pass http://localhost:8000; proxy_pass http://localhost:7878;
client_max_body_size 16m; client_max_body_size 16m;
} }
# Caveats:
* Pgbouncer is not yet supported ( 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.
```bash
cd /home/plume/Plume
rustup override set nightly-2018-05-15 # this could be needed for compilation. If errors, try 2018-05-31.
# rustup override unset # remove the override for this directory.
``` ```
* Rust nightly 2018-06-28 is known to be failing to compile diesel 1.3.2 ## Systemd integration
If you want to manage your Plume instance with systemd, you can use the following unit file (to be saved in `/lib/systemd/system/plume.service`):
```toml
[Unit]
Description=plume
[Service]
Type=simple
User=plume
WorkingDirectory=/home/plume/Plume
ExecStart=/home/dev/.cargo/bin/cargo run
TimeoutSec=30
Restart=always
[Install]
WantedBy=multi-user.target
```
## Caveats:
- Pgbouncer is not yet supported (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-05-15` or `rustup override set nightly-2018-05-31` in the Plume directory if you have issues during the compilation)
- Rust nightly 2018-06-28 is known to be failing to compile diesel 1.3.2
## Acknowledgements
Most of this documentation have been written by *gled-rs*. The systemd unit file 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).

2
docs/PREREQUISITES.md
View File

@ -5,7 +5,7 @@ As such, this notification should be updated once verified for Plume installs.
> NOTE: These instructions may help in installing a production version, but are > NOTE: These instructions may help in installing a production version, but are
intended for developers to be able to build and test their changes. If in doubt, intended for developers to be able to build and test their changes. If in doubt,
seek out documentation from your distribution package or from [the `doc` folder](doc). seek out documentation from your distribution package or from [the `docs` folder](docs).
## Installing Requirements ## Installing Requirements