94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# octomode
|
|
|
|
> *work-in-progress*
|
|
|
|
Octomode is a collective editing space for PDF making, using Etherpad, Paged.js and Flask.
|
|
|
|
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](https://cc.vvvvvvaria.org/wiki/Octomode).
|
|
|
|
### Prerequisites
|
|
|
|
* Existing [Etherpad](https://etherpad.org) installation
|
|
* [Pandoc](https://pandoc.org/) >= 2.x
|
|
* Python >= 3.11.x
|
|
|
|
### Get started
|
|
|
|
You can clone this repository to run octomode on your own computer or server.
|
|
|
|
```
|
|
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`.
|
|
|
|
```
|
|
OCTOMODE_APPLICATION_ROOT=XXX
|
|
OCTOMODE_PORTNUMBER=XXX
|
|
OCTOMODE_PAD_URL=XXX
|
|
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**: *required*, default: `https://pad.vvvvvvaria.org/` (you need API access to this pad instance)
|
|
- **OCTOMODE_PAD_API_URL**: *required*, default: `https://pad.vvvvvvaria.org/api/1.2.15/`
|
|
|
|
**Note**: you must provide a value for `OCTOMODE_PAD_API_KEY`, `OCTOMODE_PAD_URL` and `OCTOMODE_PAD_API_URL`.
|
|
|
|
Now we install the dependencies. All the `python` dependencies are listed in `requirements.txt`. To install them, you can run.
|
|
|
|
```
|
|
make setup
|
|
```
|
|
|
|
This creates a virtual environment at `.venv` and installs all the dependencies here. Next, we also need to install `pandoc`.
|
|
|
|
```
|
|
sudo apt install pandoc
|
|
```
|
|
|
|
Configure your webserver, to connect your application root (for example `octomode.domain.org` or `sub.domain.org/octomode/`) to the port on which the flask application is running (`localhost:5001` by default).
|
|
|
|
This is an example for nginx webservers:
|
|
|
|
```
|
|
# ----------------------------------------------------
|
|
# OCTOMODE
|
|
|
|
location /octomode/ {
|
|
proxy_pass http://localhost:5555;
|
|
}
|
|
|
|
```
|
|
|
|
And finally, run the application.
|
|
|
|
```
|
|
make run
|
|
```
|
|
|
|
Open the application at port `5001`, for example: http://localhost:5001
|
|
|
|
## Install with URL prefix
|
|
|
|
If you want to install octomode with an URL prefix, like <https://mydomainname.ext/octomode/>, 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`
|
|
|
|
## Which browser to use?
|
|
|
|
> **WARNING**: When working collectively, it's recommended to use the same browser
|
|
> and if possible also the same version of that browser, to get the same (or at least
|
|
> the most similar) PDF. Different operating systems and browsers render CSS rules
|
|
> slightly differently, which can result in out-of-sync layouts between across
|
|
> a group of people.
|
|
|
|
> **WARNING**: It's recommended to use Chrome/Chromium when working with Octomode.
|
|
> Firefox renders images in very low quality.
|
|
|
|
> **WARNING**: It's recommended to use Firefox when working with Octomode
|
|
> locally. Chrome or Chromium do not load external etherpads in iframes. |