octomode/README.md

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

## Local install

> **WARNING**: It's recommended to use Firefox when working with Octomode
> locally. Chrome or Chromium do not load external etherpads in iframes.

### 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**: *optional*, default: `https://pad.vvvvvvaria.org/`
- **OCTOMODE_PAD_API_URL**: *optional*, default: `https://pad.vvvvvvaria.org/api/1.2.15/`

**Note**: you must provide a value for `OCTOMODE_PAD_API_KEY`.

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
```

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`