Install Plume on Windows a complete guide #82

New issue

Closed

opened 2020-01-23 22:04:25 +00:00 by iamdoubz · 1 comment

iamdoubz commented 2020-01-23 22:04:25 +00:00 (Migrated from github.com)

Copy link

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

1. Download and install Git-SCM.
2. 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
3. Download and install rustup to the default location (Press 1 when prompted: C:\Users%USERNAME%.rustup)
4. 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'))

5. Download and install OpenSSL (I installed to C:\Extra\ssl)
6. 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!)
7. Download and install LLVM (libclang) I installed to C:\Extra\LLVM
8. Create new system variable called "LIBCLANG_PATH" with a value of C:\Extra\LLVM\bin (or wherever you installed LLVM to)
9. 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.

1. Check that rust is installed rustc --version

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

2. Check that cargo is installed cargo --version

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

3. Check that chocolatey is installed choco --version

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

4. 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

1. Download the source code git clone https://github.com/Plume-org/Plume.git
2. Enter the newly created Plume directory cd Plume
3. 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.

4. Build Plume's front end cargo install cargo-web&&cargo web deploy -p plume-front --release
5. 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.

6. Build plm and the CLI helper cargo install --no-default-features --features sqlite --path plume-cli
7. 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
MAIL_USER=admin@my.plume.url
MAIL_PASSWORD=emailpassword
MAIL_HELO_NAME=my.plume.url
MAIL_ADDRESS=no-reply@my.plume.url

# 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.

8. 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"
9. Now populate the database with preliminary tables, data, etc. diesel migration run
10. Initialise search index plm search init
11. Set up the instance plm instance new
12. 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

1. 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.

2. 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

3. If you see this output, congrats! Plume is successfully running for you!!!
4. 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.

1. Open up the Task Scheduler app
2. On right hand side, choose Create Task
3. 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)
4. Triggers tab - Begin the task At startup; Optionally Delay task for 30 seconds; Enabled (Figure 2)
5. 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)
6. Conditions - Uncheck everything
7. 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!

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

1. Launch cmd.exe as admin
2. Install SQLite3 using chocolatey choco install sqlite
3. Change directory to where SQLite was installed cd C:\ProgramData\chocolatey\lib\SQLite\tools
4. 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

5. Convert sqlite3.dll to sqlite3.lib lib /MACHINE:x64 /def:sqlite3.def /out:sqlite3.lib
6. 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
7. 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.

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 1. Download and install [Git-SCM](https://git-scm.com/downloads). 2. Download and install one of the following * [Microsoft Build Tools 2015](https://download.microsoft.com/download/E/E/D/EEDF18A8-4AED-4CE0-BEBE-70A83094FC5A/BuildTools_Full.exe) * Microsoft Visual Studio 2017 - Doesn't appear to be available anymore, but this is what I used * [Microsoft Visual Studio 2019](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16) 3. Download and install [rustup](https://win.rustup.rs/) to the default location (Press 1 when prompted: C:\Users\%USERNAME%\.rustup\) 4. Install [Chocalatey](https://chocolatey.org/) using a PowerShell v2+ prompt: ``` Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) ``` 5. Download and install [OpenSSL](https://slproweb.com/products/Win32OpenSSL.html) (I installed to C:\Extra\ssl) 6. 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!) 7. Download and install [LLVM (libclang)](https://github.com/llvm/llvm-project/releases/download/llvmorg-9.0.1/LLVM-9.0.1-win64.exe) I installed to C:\Extra\LLVM 8. Create new system variable called "LIBCLANG_PATH" with a value of `C:\Extra\LLVM\bin` (or wherever you installed LLVM to) 9. 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. 1. Check that rust is installed `rustc --version` ``` %USERNAME%@computer MINGW64 ~/Downloads $ rustc --version rustc 1.40.0 (73528e339 2019-12-16) ``` 2. Check that cargo is installed `cargo --version` ``` %USERNAME%@computer MINGW64 ~/Downloads $ cargo --version cargo 1.40.0 (bc8e4c8be 2019-11-22) ``` 3. Check that chocolatey is installed `choco --version` ``` %USERNAME%@computer MINGW64 ~/Downloads $ choco --version 0.10.15 ``` 4. 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 1. Download the source code `git clone https://github.com/Plume-org/Plume.git` 2. Enter the newly created Plume directory `cd Plume` 3. 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. 4. Build Plume's front end `cargo install cargo-web&&cargo web deploy -p plume-front --release` 5. 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. 6. Build plm and the CLI helper `cargo install --no-default-features --features sqlite --path plume-cli` 7. 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 MAIL_USER=admin@my.plume.url MAIL_PASSWORD=emailpassword MAIL_HELO_NAME=my.plume.url MAIL_ADDRESS=no-reply@my.plume.url # 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. 8. 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" 9. Now populate the database with preliminary tables, data, etc. `diesel migration run` 10. Initialise search index `plm search init` 11. Set up the instance `plm instance new` 12. 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 1. 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. 2. 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 ``` 3. If you see this output, congrats! Plume is successfully running for you!!! 4. 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. 1. Open up the Task Scheduler app 2. On right hand side, choose Create Task 3. **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) 4. **Triggers tab** - Begin the task At startup; Optionally Delay task for 30 seconds; Enabled (Figure 2) 5. **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) 6. **Conditions** - Uncheck everything 7. **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! 1. You need to have installed URL Rewrite (Figure 4) 2. From the Sites, choose your site, in the middle pane, double click URL Rewrite. 3. On right hand side, Add Rule, Blank Rule 4. Name it Plume with pattern (.*) with Action type Rewrite and Rewrite URL of http://127.0.0.1:7878/{R:1} (Figure 5) 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 1. Launch cmd.exe as admin 2. Install SQLite3 using chocolatey `choco install sqlite` 3. Change directory to where SQLite was installed `cd C:\ProgramData\chocolatey\lib\SQLite\tools` 4. 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` 5. Convert sqlite3.dll to sqlite3.lib `lib /MACHINE:x64 /def:sqlite3.def /out:sqlite3.lib` 6. 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` 7. 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](https://github.com/iamdoubz/Plume4Windows).

iamdoubz commented 2020-02-03 16:00:25 +00:00 (Migrated from github.com)

Copy link

Will be added to docs via this.

Will be added to docs via [this](https://github.com/Plume-org/docs/pull/83).

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

trans-fr

dev

No results found.

Labels

Clear labels   

bug

Something isn't working

  

dependencies

Pull requests that update a dependency file

  

duplicate

This issue or pull request already exists

  

enhancement

New feature or request

  

good first issue

Good for newcomers

  

help wanted

Extra attention is needed

  

invalid

This doesn't seem right

  

question

Further information is requested

  

wontfix

This will not be worked on

No labels

bug

dependencies

duplicate

enhancement

good first issue

help wanted

invalid

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: plume/documentation#82

No description provided.