plume-org / docs Goto Github PK

View Code? Open in Web Editor NEW

6.0 7.0 9.0 1.09 MB

The documentation for Plume

Home Page: https://docs.joinplu.me

License: GNU General Public License v3.0

Ruby 17.51% HTML 38.83% JavaScript 7.42% Shell 2.44% SCSS 33.81%

middleman docs plume

docs's People

Contributors

Stargazers

Watchers

Forkers

zcdunn mscherer po-lak novaphoenix epsilon-phase matthiasbeyer kitaitimakoto pullopen

docs's Issues

Internationalization

The docs should be translated too.

installation instruction fail for mac

Installing gettext via homebrow does not add it to the path by default, so running brew install gettext is not enough to be able to compile Plume. It actually require brew link gettext --force (see Homebrew/legacy-homebrew#7621)

sample docker-compose returns html

The doc says to curl https://docs.joinplu.me/docker-compose.sample.yml to get docker configuration, however as of now, it returns a webpage instead of actual yml

Broken CSS

There is no default text color specified. To reproduce, configure your browser to use white text on black
background as fallback.

New config parameters

Document some new configuration parameters :

SEARCH_INDEX : path of the search index
PLUME_LOGO : path to the main logo (/static/ is prefixed automatically)
PLUME_LOGO_FAVICON : same
PLUME_LOGO_{integer} : an alternative logo for the web-manifest, assume the image is a square of dimension {integer}px (multiple can be provided)

add some places we are

add Docker-hub, Liberapay, and maybe other places to this list

document which markdown flavor is used in Plume

(it's CommonMark)

Mention Yunohost and Lollipop Cloud

As installation methods.

Say that there are pre-built docker images

Thanks to @mcrosson there are pre-built images available at https://docker.lollipopcloud.solutions/. I think most people will prefer to use them instead of building them manually, so we should probably mention that in the installation docs.

Documentation doesn't mention ROCKET_ADDRESS

When setting up Plume, I found I couldn't access my instance when visiting the URL I had set up, this was because Plume wasn't running on the same host as the Reverse Proxy, and it had bound to localhost:7878 and not [my host's ip]:7878. I found the env("ROCKET_ADDRESS") when looking through the source code and got it set up properly, but not everyone will be able to read Rust code.

User guide

But maybe once Plume is more stable.

Don't use interactive mode for docker setup

cc @papey

Rust docs

Maybe we could host documentation for the source code, to make it easier to explore? But that would require better source code documentation first.

Document plume-ci

So that people at least know it exists

Move the arrows in the menu to the right

Having them on the left creates a non-existent hierarchy between pages with "subpages" and pages that don't.

Documentation improvements

Review the docker-compose setup
Plume require HTTPS connection (see Plume-org/Plume#412)

Exit su postgres

In the install docs, we say to do su postgres to create the DB but we never give the instructions to exit it, it may be confusing.

Add a language switcher

The autodetection may not always work as expected

Command errors in documentation

Documentation says :

plm migration run

But this is not a valid command in 0.0.3-alpha-2 release.

See this thread for a real life exemple

Update release process

We now use cargo release
A Crowdin API key (v3) is needed.

Document development setup

Especially how to setup HTTPS (I think Caddy and mkcert is the way to go (we need mkcert since caddy uses self signed certificates for local sites, which are rejected when federating))

Install Plume on Ubuntu 18 a complete guide

Install Plume on Ubuntu 18.04

A meditative guide

This was 8 hours of solid work in order to get every single detailed hashed out for installing from source on Ubuntu 18. I hope this helps somebody.

What this guide will cover

Must have a server setup already with apache2 as your web server
Will be using PostgreSQL as your database

Givens

apachectl -V "Apache2" needs to be version 2.4.17 or higher
A working knowledge of bash, command line typing, and lack of fat fingers :D
You are using systemd to start and stop all of your services
My Ubuntu 18.04 server is running in a VM on a Windows 10 Pro laptop... brief specs:
a. i7-4810MQ, 24GB RAM, 1TB SSD Windows OS, 2TB SSD Data drive with VM files on it
b. 4 of 8 threads and 8GB dedicated to VM (runs great!)

Steps

Install default dependencies: sudo apt install gettext git curl gcc make openssl libssl-dev pkg-config
Install PostgreSQL 11
a. Guide I used
b. sudo apt install wget ca-certificates
c. wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
d. sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs` -pgdg main" >> /etc/apt/sources.list.d/pgdg.list'
e. sudo apt update
f. sudo apt install postgresql postgresql-contrib libpq-dev
g. Helpful PostgreSQL tips:
i. Connect to interface (similar to mysql -u root -p): sudo su - postgres psql
ii. List databases (from psql window): \l
iii. Quit/Exit: \q
Create a new user for Plume
a. sudo adduser plume
b. Set a password for it that you can remember
c. Log in as plume: su - plume
d. Go to plume's home directory: cd ~
Install Rust
a. curl https://sh.rustup.rs -sSf | sh
b. When prompted for Option 1, 2, or 3, press 1 [Proceed with installation (default)], then enter
c. This will take a bit depending on your system network's connection ~10 minutes
d. At the time of this writing, you should get something like stable installed - rustc 1.37.0 (eae3437df 2019-08-13) and Rust is installed now. Great!
Tell your system how to use Rust export PATH="$PATH:/home/plume/.cargo/bin:/home/plume/.local/bin:/usr/local/sbin"
a. You need to put this in you .bashrc file source:
i. nano ~/.bashrc
ii. export PATH="$HOME/.cargo/bin:$PATH"
b. Maybe this too?????: source $HOME/.cargo/env
c. Go ahead and exit (log out of plume)
d. Log back in as plume
e. cd ~
Check to see if Rust and Cargo are actually installed
a. rustc --version
- Response: rustc 1.37.0 (eae3437df 2019-08-13)
b. cargo --version
- Response: cargo 1.37.0 (9edd08916 2019-08-02)
Download Plume and enter the directory
a. git clone https://github.com/Plume-org/Plume.git&&cd Plume

* Note *: the next command can and will take a long time

Install Plume and CLI tools (~36 minutes to build and compile)
a. cargo clean && cargo build --features postgres && cargo install --debug --force --features postgres
Build plm and CLI helper (~12 minutes to build and compile)
a. cargo install --no-default-features --debug --force --features postgres --path plume-cli
To start PostgreSQL, and create a user and database, you will need to use a root account
Ensure the PostgreSQL service is running, use b to start it if not
a. sudo service postgresql status
b. sudo service postgresql start
Create user and database for Plume to use
a. sudo -u postgres createuser -P plume
i. Make a secure password for your plume PostgreSQL user!
b. sudo -u postgres createdb -O plume plume
Now you can go back to your plume user account and be in the Plume directory
a. cd ~/Plume

Create an .env file that the plume server will read
a. nano .env and populate with this changing the postgres user name, password, database name and ROCKET_SECRET_KEY as needed

# Postgres SQL setup
DATABASE_URL=postgres://plume:[email protected]:5432/plume

# For PostgreSQL: migrations/postgres
MIGRATION_DIRECTORY=migrations/postgres

# The domain on which your instance will be available
BASE_URL=my.plume.url

# Secret key used for private cookies and CSRF protection `openssl rand -base64 32`
ROCKET_SECRET_KEY=
ROCKET_ADDRESS=127.0.0.1
ROCKET_PORT=7878

# Mail settings
MAIL_SERVER=my.plume.url
[email protected]
MAIL_PASSWORD=emailpassword
MAIL_HELO_NAME=my.plume.url
[email protected]

# Custom icons
#PLUME_LOGO=icons/custom/myicons/plume.png
#PLUME_LOGO_FAVICON=icons/custom/myicons/plume32.png
#PLUME_LOGO_48=icons/custom/myicons/plume48.png
#PLUME_LOGO_72=icons/custom/myicons/plume72.png
#PLUME_LOGO_96=icons/custom/myicons/plume96.png
#PLUME_LOGO_144=icons/custom/myicons/plume144.png
#PLUME_LOGO_160=icons/custom/myicons/plume160.png
#PLUME_LOGO_192=icons/custom/myicons/plume192.png
#PLUME_LOGO_256=icons/custom/myicons/plume256.png
#PLUME_LOGO_512=icons/custom/myicons/plume512.png

Populate the database
a. diesel migration run
Setup your instance
a. plm instance new
b. plm users new --admin
Create search index
a. plm search init

You should be ready to test everything before you configure systemd using
a. plume
b. If there is anything I forgot, it will tell you here
c. If not, you should get a bunch of text to the extent of

plume@computer:~/Plume$ plume
Configuration read from /home/plume/Plume/.env
🔧 Configured for development.
    => address: 127.0.0.1
    => port: 9092
    => log: normal
    => workers: 8
    => secret key: provided
    => limits: forms = 128KiB, json* = 1MiB
    => keep-alive: 5s
    => tls: disabled
🛰  Mounting /:
...
🚀 Rocket has launched from http://127.0.0.1:7878

If you have gotten this far, congrats! Plume is ready to go!

Configure plume to start as a service on boot
a. sudo nano /etc/systemd/system/plume.service and in that file

[Unit]
Description=plume - federated blogging application
After=network.target postgresql.service

[Service]
Type=simple
User=plume
WorkingDirectory=/home/plume/Plume
ExecStart=/home/plume/.cargo/bin/plume
TimeoutSec=30
SyslogIdentifier=plume
Restart=always

[Install]
WantedBy=multi-user.target

Enable the service with sudo systemctl enable plume
Start the service with sudo service plume start
Reverse Proxy for Apache2
a. Please use this config

Document supported programming languages

For syntax highlighting. Their names and "aliases" (for instance python instead of Python) should be listed.

Document the timeline syntax

Install Plume on Windows a complete guide

Until I figure out my password (to upload my SSH and GPG keys), I will save the guide here.

Compile Plume on Windows

My specific setup:

Installed Visual Studio 2017, which contains the build tools necessary for compiling sqlite in this guide
Built using Windows 10 Pro 1909 x64 18363.535
For OpenSSL and LLVM, I installed to a folder on PC where I have a bunch of crap (GoLang, FFMPEG, nodejs, etc) for simplicity's sake C:\Extra
I installed Plume to my Downloads folder. For production setups, I recommend installing to C:\Plume
Built to use SQLite3; PostgreSQL will not be covered in this guide (yet)
Patience... took almost 10 hours to figure out so that it will take you only an hour or so

Outline:

Install all requirements and packages
Checks and balances
Begin building and compiling
Error checking
Create service that can be start/stopped/restarted (working... kinda :/)
Create IIS Reverse Proxy

Requirements

Download and install Git-SCM.
Download and install one of the following
- Microsoft Build Tools 2015
- Microsoft Visual Studio 2017 - Doesn't appear to be available anymore, but this is what I used
- Microsoft Visual Studio 2019
Download and install rustup to the default location (Press 1 when prompted: C:\Users%USERNAME%.rustup)
Install Chocalatey using a PowerShell v2+ prompt:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Download and install OpenSSL (I installed to C:\Extra\ssl)
Create new system variable called "OPENSSL_DIR" with a value of C:\Extra\ssl (or wherever you installed OpenSSL NOTE: this is not to the bin folder, it must be to root!)
Download and install LLVM (libclang) I installed to C:\Extra\LLVM
Create new system variable called "LIBCLANG_PATH" with a value of C:\Extra\LLVM\bin (or wherever you installed LLVM to)
Reboot your PC :D

Check and Balances

Launch Git Bash by right clicking on your desktop and choosing "Git Bash Here". The rest of the commands will be run from this console unless otherwise stated.

Check that rust is installed rustc --version

%USERNAME%@computer MINGW64 ~/Downloads
$ rustc --version
rustc 1.40.0 (73528e339 2019-12-16)

Check that cargo is installed cargo --version

%USERNAME%@computer MINGW64 ~/Downloads
$ cargo --version
cargo 1.40.0 (bc8e4c8be 2019-11-22)

Check that chocolatey is installed choco --version

%USERNAME%@computer MINGW64 ~/Downloads
$ choco --version
0.10.15

Check that OpenSSL is installed openssl version

%USERNAME%@computer MINGW64 ~/Downloads
$ openssl version
OpenSSL 1.1.1d  10 Sep 2019

If you get any Not Found errors, make sure that your folder paths are correct in your environment. Once everything returns a version, you may proceed.

Building and Compiling

Download the source code git clone https://github.com/Plume-org/Plume.git
Enter the newly created Plume directory cd Plume
Install diesel_cli cargo +stable install diesel_cli --no-default-features --features sqlite --version '=1.4.0' --verbose

NOTE - you may get an error similar to this:

  = note: LINK : fatal error LNK1181: cannot open input file 'sqlite3.lib'


error: aborting due to previous error

error: failed to compile `diesel_cli v1.4.0`, intermediate artifacts can be found at `C:\Users\%USERNAME%\AppData\Local\Temp\cargo-installToiK1l`

Caused by:
  could not compile `diesel_cli`.

If you do, go to the "Making SQLite3.lib" section, else continue.

Build Plume's front end cargo install cargo-web&&cargo web deploy -p plume-front --release
Build Plume's back end cargo install --no-default-features --features sqlite --path .

If you get an error here, go to the "Making SQLite3.lib" section step 5/6, else continue.

Build plm and the CLI helper cargo install --no-default-features --features sqlite --path plume-cli
Create environment file ".env" (there should be a .env.example file already, just copy that and rename it) with the contents:

# Postgres SQL setup
DATABASE_URL=C:/Users/%USERNAME%/Downloads/Plume/plume.db

# For PostgreSQL: migrations/postgres
MIGRATION_DIRECTORY=migrations/sqlite

# The domain on which your instance will be available
BASE_URL=my.plume.url

# Secret key used for private cookies and CSRF protection `openssl rand -base64 32`
ROCKET_SECRET_KEY=
ROCKET_ADDRESS=127.0.0.1
ROCKET_PORT=7878

# Mail settings
MAIL_SERVER=my.plume.url
[email protected]
MAIL_PASSWORD=emailpassword
MAIL_HELO_NAME=my.plume.url
[email protected]

# Custom icons
#PLUME_LOGO=icons/custom/myicons/plume.png
#PLUME_LOGO_FAVICON=icons/custom/myicons/plume32.png
#PLUME_LOGO_48=icons/custom/myicons/plume48.png
#PLUME_LOGO_72=icons/custom/myicons/plume72.png
#PLUME_LOGO_96=icons/custom/myicons/plume96.png
#PLUME_LOGO_144=icons/custom/myicons/plume144.png
#PLUME_LOGO_160=icons/custom/myicons/plume160.png
#PLUME_LOGO_192=icons/custom/myicons/plume192.png
#PLUME_LOGO_256=icons/custom/myicons/plume256.png
#PLUME_LOGO_512=icons/custom/myicons/plume512.png

NOTE: in order to use the Windows Task Scheduler to start/stop, you need a full file path to database file with forward slashes... Backslashes will result in errors.

Copy the sqlite3.dll from "C:\ProgramData\chocolatey\lib\SQLite\tools" to where plm.exe and plume.exe was compiled "C:\Users%USERNAME%.cargo\bin"
Now populate the database with preliminary tables, data, etc. diesel migration run
Initialise search index plm search init
Set up the instance plm instance new
Create an admin user plm users new --admin -n "adminusername" -N "Human Readable Admin Name" -b "Biography of Admin here" -p hackmeplease

You should be ready to start testing!

Error Checking and Testing

Launch Plume from cmd, git bash, or powershell plume

You may get error from not supplying a valid secret key

%USERNAME%@computer MINGW64 ~/Downloads/Plume (master)
$ plume
Configuration read from C:\Users\%USERNAME%\Downloads\Plume\.env
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: InvalidSecretKey', src/main.rs:146:26
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace.

Open your .env file and make sure the ROCKET_SECRET_KEY= is filled in. You may use openssl rand -base64 32 to generate a valid key.

Try again plume

%USERNAME%@computer MINGW64 ~/Downloads/Plume (master)
$ plume
Configuration read from C:\Users\%USERNAME%\Downloads\Plume\.env
Warning: the email server is not configured (or not completely).
Please refer to the documentation to see how to configure it.
Configured for production.
    => address: 127.0.0.1
    => port: 7878
    => log: critical
    => workers: 16
    => secret key: provided
    => limits: forms = 128KiB, json* = 1MiB
    => keep-alive: 5s
    => tls: disabled
Rocket has launched from http://127.0.0.1:7878

If you see this output, congrats! Plume is successfully running for you!!!
Just to be sure though, go ahead and open it up in your browser: http://127.0.0.1:7878/

Service Setup

Once everything is working, you may be annoyed by having to always open a command prompt to start Plume. We can configure it to start on boot via Task Scheduler.

Open up the Task Scheduler app
On right hand side, choose Create Task
General tab - Name: "Plume"; Description: "Plume: a federated blogging application"; Run whether user is logged on or not; Run with highest privileges; Configure for Windows 10 (Figure 1)
Triggers tab - Begin the task At startup; Optionally Delay task for 30 seconds; Enabled (Figure 2)
Actions - Action: Start a program; Browse to plume.exe (default is C:\Users%USERNAME%.cargo\bin\plume.exe); Start in: C:\path\to.env (Figure 3)
Conditions - Uncheck everything
Settings - Allow task to be run on demand; Run task as soon as possible after a scheduled start is missed; If the running task does not end when requested, for it to stop; Do not start a new instance


Figure 1


Figure 2


Figure 3

Reverse Proxy using IIS 8.5

Note: I have yet to get this to work with a subdirectory. So, if your domain is https://mydomain.com, it can only work there and not at https://mydomain.com/plume as far as I am aware. If anyone figures this out, please let me know!

You need to have installed URL Rewrite (Figure 4)
From the Sites, choose your site, in the middle pane, double click URL Rewrite.
On right hand side, Add Rule, Blank Rule
Name it Plume with pattern (.*) with Action type Rewrite and Rewrite URL of http://127.0.0.1:7878/{R:1} (Figure 5)
Apply


Figure 4


Figure 5

If you need to use a subdirectory, you can create a Server Farm called Plume, with a server of localhost, and a http port of 7878 and follow these steps:

You then need to install Application Request Routing Cache in IIS
After installing double click on Your server name, then Applications Request Routing Cache.
On right hand side, select Server Proxy Settings...
Enable the proxy, HTTP version Pass through, under Proxy Type, check Use URL Rewrite to inspect incoming requests, check Enable SSL offloading, and for Reverse proxy use the name of your server farm: Plume
Apply
Then on right hand side, select URL Rewrite...
Should be something called either ARR_Plume_loadbalance or ARR_server_proxy. Edit it.
Patter should be Regular Expression with pattern of ^plume$|^plume/(.*) where plume is the subdirectory you want to use.
Action type should be Route to Server Farm, Scheme http://, Server farm Plume, Path /{R:1}

Making SQLite3.lib

Launch cmd.exe as admin
Install SQLite3 using chocolatey choco install sqlite
Change directory to where SQLite was installed cd C:\ProgramData\chocolatey\lib\SQLite\tools
Launch Visual Studio 2017 environment "C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64

Launch Visual Studio 2019 environment "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64
Launch Microsoft Build Tools "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86_amd64

Convert sqlite3.dll to sqlite3.lib lib /MACHINE:x64 /def:sqlite3.def /out:sqlite3.lib
Copy sqlite3.lib and sqlite3.exp to where you installed rustup C:\Users\%USERNAME%\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\x86_64-pc-windows-msvc\lib
After compiling, building, and installing diesel_cli, you will also need to copy sqlite3.lib and sqlite3.exp to "C:\Users\%USERNAME%\.rustup\toolchains\nightly-2020-01-15-x86_64-pc-windows-msvc\lib\rustlib\x86_64-pc-windows-msvc\lib"

Don't want to compile from source? Try this.

Contributors directory

We should have a page listing people contributing (or who contributed to the project) to make our organization clearer both for ourselves and external people.

Info that should be on this page

name and/or pseudonyms in the different spaces of the project (and eventually a fediverse @, or something to contact them if needed)
pronouns
skills
open for mentoring
how they contribute to Plume (in general, or examples of specific examples)
something else?

document existance of wasm artifacts

Following Plume-org/Plume#570 and Plume-org/Plume#571, we can now provide wasm binaries for non tier 1 platforms.
This should be documented (and those binaries distribued) so that people wanting to build Plume on "rare" platforms can do so without the headache of doing whatever was done to make arm build fine