From 7d02db49b0d3538a6554aed95cd9c385ac38f18e Mon Sep 17 00:00:00 2001 From: decentral1se Date: Fri, 24 Nov 2023 15:35:25 +0100 Subject: [PATCH] docs: focus on local install, ".env" before "make setup" --- README.md | 73 ++++++++++++++++++++++++------------------------------- 1 file changed, 32 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 4a8ed0d..089840d 100644 --- a/README.md +++ b/README.md @@ -6,37 +6,29 @@ Octomode is a collective editing space for PDF making, using Etherpad, Paged.js Inspired by the multi-centered, tentacular cognition capabilities of the octopus, we imagined a space in which the artificial boundaries of writing and design can be crossed; where writing, editing and designing can be done in one environment simultaneously, allowing the format to influence the matter and vice-versa. -More expanded documentation can be found here: +More expanded documentation can be found [here](https://cc.vvvvvvaria.org/wiki/Octomode). -An installation guide can be found below. +## Local install -## Install octomode +> **WARNING**: It's recommended to use Firefox when working with Octomode +> locally. Chrome or Chromium do not load external etherpads in iframes. -You can clone this repository to run octomode on your own computer or server. - -`git clone https://git.vvvvvvaria.org/varia/octomode.git` - -Install the dependencies. - -All the `python` dependencies are listed in `requirements.txt` - -To install them, you can run: - -`make setup` +### Prerequisites -This creates a virtual environment at `.venv/` and installs all the dependencies here. +* Existing [Etherpad](https://etherpad.org) installation +* [Pandoc](https://pandoc.org/) >= 2.x +* Python >= 3.11.x -Next to this, you also need to install `pandoc`. +### Get started -`sudo apt install pandoc` - -Now we need to configure *octomode*: - -`cd octomode` +You can clone this repository to run octomode on your own computer or server. -`nano .env` +``` +git clone https://git.vvvvvvaria.org/varia/octomode.git +cd octomode +``` -Configure your environment, save the following configuration settings as to a file called `.env`: +Configure your environment, save the following configuration settings as to a file called `.env`. ``` OCTOMODE_APPLICATION_ROOT=XXX @@ -46,35 +38,34 @@ OCTOMODE_PAD_API_URL=XXX OCTOMODE_PAD_API_KEY=XXX ``` +- **OCTOMODE_PAD_API_KEY**: *required*, **no default** - **OCTOMODE_APPLICATION_ROOT**: *optional*, default: `/` - **OCTOMODE_PORTNUMBER**: *optional*, default: `5001` - **OCTOMODE_PAD_URL**: *optional*, default: `https://pad.vvvvvvaria.org/` - **OCTOMODE_PAD_API_URL**: *optional*, default: `https://pad.vvvvvvaria.org/api/1.2.15/` -- **OCTOMODE_PAD_API_KEY**: *required*, **no default** - -(Note: You must provide a value for `OCTOMODE_PAD_API_KEY`.) -`make run` (runs the Flask application) +**Note**: you must provide a value for `OCTOMODE_PAD_API_KEY`. -Open the application at port `5001`, for example: or . +Now we install the dependencies. All the `python` dependencies are listed in `requirements.txt`. To install them, you can run. -## Install octomode with an URL prefix - -If you want to install octomode with an URL prefix, like , then you can use the gunicorn WSGI. - -If you have ran the `make setup` command already, then `gunicorn` is already installed. +``` +make setup +``` -Configure your application root URL in your `.env` file. +This creates a virtual environment at `.venv` and installs all the dependencies here. Next, we also need to install `pandoc`. -You can simply run *octomode* now with the following command to run it with `gunicorn` (and not the built-in Flask dev server): +``` +sudo apt install pandoc +``` -`make action` +And finally, run the application. -### Dependencies +``` +make run +``` -* pandoc -* python dependencies, see: `requirements.txt` +Open the application at port `5001`, for example: http://localhost:5001 -## Use octomode locally +## Install with URL prefix -It's recommended to use Firefox when working with octomode locally. Chrome or Chromium do not load external etherpads in iframes. +If you want to install octomode with an URL prefix, like , then you can use the gunicorn WSGI. If you have ran the `make setup` command already, then `gunicorn` is already installed. Configure your application root URL in your `.env` file. You can simply run *octomode* now with the following command to run it with `gunicorn` (and not the built-in Flask dev server): `make action`