Put all documentation in the docs folder
This commit is contained in:
Bat
@@ -0,0 +1,141 @@
|
||||
# Development Guide
|
||||
|
||||
## Running Plume locally
|
||||
|
||||
### Mac OSX
|
||||
|
||||
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.
|
||||
|
||||
### 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"),
|
||||
also owned by the "plume" user, but with a different name. Then, you'll need to run the
|
||||
migrations for this database too.
|
||||
|
||||
```
|
||||
diesel migration run --database-url postgres://plume:plume@localhost/my_other_plume_db
|
||||
```
|
||||
|
||||
To run this other instance, you'll need to give two environment variables:
|
||||
|
||||
- `ROCKET_PORT`, the port on which your app will run
|
||||
- `DB_NAME`, the name of the database you just created
|
||||
|
||||
```
|
||||
ROCKET_PORT=3033 DB_NAME=my_other_plume_db cargo run
|
||||
```
|
||||
|
||||
If you don't want to setup HTTPS locally, you can also disable it by running your instance with `USE_HTTPS=0` set.
|
||||
|
||||
```
|
||||
USE_HTTPS=0 cargo run
|
||||
```
|
||||
|
||||
#### 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.
|
||||
|
||||
```
|
||||
git remote add upstream git@github.com/myname/Plume.git
|
||||
# Alt # git remote add upstream https://github.com/myname/Plume.git
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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 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:
|
||||
|
||||
- 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
|
||||
|
||||
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:
|
||||
|
||||
```jinja
|
||||
<p>{{ "Hello, world!" | _ }}</p>
|
||||
|
||||
<p>{{ "You have {{ count }} new notifications" | _n(singular="You have one new notification", count=n_notifications) }}</p>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
The second step is to add them to POT file. To add a simple message, just do:
|
||||
|
||||
```po
|
||||
msgid "Hello, world" # The string you used with your filter
|
||||
msgstr "" # Always empty
|
||||
```
|
||||
|
||||
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!
|
||||
@@ -0,0 +1,72 @@
|
||||
# How to install Plume on a Debian stretch:
|
||||
|
||||
## Basic setup:
|
||||
|
||||
```bash
|
||||
apt update
|
||||
apt install gettext postgresql postgresql-contrib libpq-dev
|
||||
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:
|
||||
|
||||
```bash
|
||||
service postgresql start
|
||||
cargo run # this will configure and launch Plume on the server.
|
||||
```
|
||||
|
||||
## If you want to run Plume with a remote DB this time ( Postgresql is not installed on the same server/container):
|
||||
|
||||
* On the DB server:
|
||||
|
||||
```bash
|
||||
service postgresql start
|
||||
su - postgres
|
||||
createuser -d -P plume
|
||||
createdb -O plume plume
|
||||
```
|
||||
|
||||
* On the Plume server:
|
||||
|
||||
```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:
|
||||
|
||||
location / {
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $http_host;
|
||||
|
||||
proxy_pass http://localhost:8000;
|
||||
|
||||
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
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
# Making Plume available in your language
|
||||
|
||||
*You will need to have basic git and GitHub knownledge to follow this guide. But we plan to setup a more user-friendly translation tool in the future.*
|
||||
|
||||
To translate Plume in your language, you'll first need to make sure it is listed in the `po/LINGUAS` file. If it is not, you can ask anybody with a development environment to add it (or do it yourself if you have a development environment). Once it will be here, Plume must be launched once to generate all the needed files.
|
||||
|
||||
Then you can start translating. Find the file corresponding to your locale, which is `po/YOUR_LOCALE.po`, and open it. Inside, you have a list of strings to translate. There are two kind of translatable strings.
|
||||
|
||||
## Simple strings
|
||||
|
||||
They look like this:
|
||||
|
||||
```po
|
||||
msgid "Hello, world"
|
||||
msgstr ""
|
||||
```
|
||||
|
||||
What is next to `msgid` is the string in English. To translate it, just fill the `msgstr` field with the translation.
|
||||
|
||||
## Strings with plural forms
|
||||
|
||||
Sometimes, strings may change depending on a number (for instance, a post counter). In the `.po` files, these strings look like this:
|
||||
|
||||
```
|
||||
msgid "One post"
|
||||
msgid_plural "{{ count }} posts"
|
||||
msgstr[0] ""
|
||||
msgstr[1] ""
|
||||
```
|
||||
|
||||
Then you should fill the two `msgstr` field, one with the singular form, the second with the plural one. If your language as more than two forms, you can add another one by following the same pattern (`msgstr[n] ""`).
|
||||
|
||||
## Interpolation
|
||||
|
||||
Strings you translate may contain data from Plume (a username for instance). To tell Plume where to put these data, surround their identifier by `{{` and `}}`. The identifier is also present in this form in the English string to translate (this what you can see above, with the `{{ count }} posts` message).
|
||||
|
||||
## Note
|
||||
|
||||
When translating, please try to be as inclusive as possible.
|
||||
@@ -0,0 +1,96 @@
|
||||
# Installing Software Prerequisites
|
||||
|
||||
These instructions have been adapted from the Aardwolf documentation, and may not be accurate.
|
||||
As such, this notification should be updated once verified for Plume installs.
|
||||
|
||||
> 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,
|
||||
seek out documentation from your distribution package or from [the `doc` folder](doc).
|
||||
|
||||
## Installing Requirements
|
||||
|
||||
### Installing PostgreSQL
|
||||
|
||||
In order to run the Plume backend, you will need to have access to a
|
||||
[PostgreSQL](https://www.postgresql.org/) database. There are a few options for doing this, but for
|
||||
this guide we’re going to assume you are running the database on your
|
||||
development machine.
|
||||
|
||||
#### Linux/OSX Instructions
|
||||
|
||||
If you're on an Ubuntu-like machine, you should be able to install
|
||||
PostgreSQL like this:
|
||||
|
||||
$ sudo apt-get update
|
||||
$ sudo apt-get install postgresql postgresql-contrib
|
||||
|
||||
If you see an error like:
|
||||
|
||||
= note: /usr/bin/ld: cannot find -lpq
|
||||
collect2: error: ld returned 1 exit statusb
|
||||
|
||||
Then you may need to install the libpq (PostgreSQL C-library) package as well :
|
||||
|
||||
$ sudo apt-get install libpq-dev
|
||||
|
||||
If you're on OSX and using `brew`, do
|
||||
|
||||
$ brew update
|
||||
$ brew install postgres
|
||||
|
||||
For Gentoo (eselect-postgresql is optional),
|
||||
|
||||
# emerge --sync
|
||||
# emerge -av postgresql eselect-postgresql
|
||||
|
||||
For Fedora/CentOS/RHEL, do
|
||||
|
||||
# dnf install postgresql-server postgresql-contrib mariadb-devel libsq3-devel libpqxx libpqxx-devel
|
||||
|
||||
|
||||
#### Windows Instructions
|
||||
|
||||
For Windows, just download the installer [here](https://www.enterprisedb.com/downloads/postgres-postgresql-downloads#windows) and run it. After installing, make sure to add the <POSTGRES INSTALL PATH>/lib directory to your PATH system variable.
|
||||
|
||||
### Installing rustup
|
||||
|
||||
> Note: Rustup managed installations do appear to co-exist with system
|
||||
installations on Gentoo, and should work on most other distributions.
|
||||
If not, please file an issue with the Rust and Rustup teams or your distribution’s
|
||||
managers.
|
||||
|
||||
Next, you’ll need to have the [Rust](https://rust-lang.org/) toolchain
|
||||
installed. The best way to do this is to install
|
||||
[rustup](https://rustup.rs), which is a Rust toolchain manager.
|
||||
|
||||
#### Linux/OSX Instructions
|
||||
|
||||
Open your terminal and run the following command:
|
||||
|
||||
$ curl https://sh.rustup.rs -sSf | sh
|
||||
|
||||
For those who are (understandably) uncomfortable with piping a shell
|
||||
script from the internet directly into `sh`, you can also
|
||||
[use an alternate installation method](https://github.com/rust-lang-nursery/rustup.rs/#other-installation-methods).
|
||||
|
||||
#### Windows Instructions
|
||||
|
||||
If you don't already have them, 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. That's it!
|
||||
|
||||
### Installing Rust Toolchain
|
||||
|
||||
Once you have `rustup` installed, make sure you have the `nightly` rust
|
||||
toolchain installed:
|
||||
|
||||
$ rustup toolchain install nightly
|
||||
|
||||
### Installing GetText
|
||||
|
||||
GetText is the tool we use to manage translations. It will be needed at runtime, since we only compile
|
||||
translation files when starting Plume.
|
||||
|
||||
#### Ubuntu-like Linux
|
||||
|
||||
$ sudo apt-get install gettext
|
||||
Reference in New Issue
Block a user