Manetta: /* How to install octomode? */

2026-04-07T13:31:47Z

How to install octomode?

← Older revision		Revision as of 13:31, 7 April 2026
Line 13:		Line 13:
	$ sudo su		$ sudo su
	# cd /opt/		# cd /opt/
	# git clone https://git.vvvvvvaria.org/~~varia~~/octomode.git		# git clone https://git.vvvvvvaria.org/CC/octomode.git

	===Step 2: Make an octomode system user===		===Step 2: Make an octomode system user===

Manetta: Created page with "''Installation notes for octomode.'' ==How to install octomode?== The code we use + an installation guide can be found here: https://git.vvvvvvaria.org/CC/octomode A more expanded installation guide can be found below, written in the context of rosa in March 2022: https://hub.vvvvvvaria.org/rosa/ ===Step 1: Download the octomode code from the Varia git=== First go to the location where you want to install octomode. This should be outside of the public webserver..."

2026-03-25T12:24:38Z

Created page with "''Installation notes for octomode.'' ==How to install octomode?== The code we use + an installation guide can be found here: https://git.vvvvvvaria.org/CC/octomode A more expanded installation guide can be found below, written in the context of rosa in March 2022: https://hub.vvvvvvaria.org/rosa/ ===Step 1: Download the octomode code from the Varia git=== First go to the location where you want to install octomode. This should be outside of the public webserver..."

New page

''Installation notes for [[octomode]].''

==How to install octomode?==

The code we use + an installation guide can be found here: https://git.vvvvvvaria.org/CC/octomode

A more expanded installation guide can be found below, written in the context of rosa in March 2022: https://hub.vvvvvvaria.org/rosa/

===Step 1: Download the octomode code from the Varia git===

First go to the location where you want to install octomode. This should be outside of the public webserver folders, as we will have to save an API key of the etherpad at some point, and you don’t want to share that key in public. Also, switch to the root user for this step.

$ sudo su
# cd /opt/
# git clone https://git.vvvvvvaria.org/varia/octomode.git

===Step 2: Make an octomode system user===

We will make an “octomode” user on the server to run octomode with this user. In this way we can restrict the access of this user to the rest of the server. It’s a way to make sure that the pads in octomode cannot be used to write code in a specific way, that it can be executed on the server.

Make a system user called “octomode”.

# useradd --system --no-create-home --shell=/sbin/nologin octomode

Give read and write access + ownership to the <code>/opt/octomode</code> folder to the octomode user.

# chown -R octomode:octomode /opt/octomode

# chmod -R u+rw /opt/octomode

To handle the limited folder access, i’m not sure what to do.

Maybe a so called <code>chroot</code> can be used?

Asking for advice here: https://git.vvvvvvaria.org/varia/octomode/issues/2#issuecomment-757

===Step 3: Get the API key of the etherpad you want to use===

This can be a local one which is running on the same server, or an etherpad that is running somewhere else.

# cat /opt/etherpad/APIKEY.txt

If you're using a newer version of etherpad, the <code>APIKEY.txt</code> is not used anymore for accessing the API. But you can still enable it!

# sudo /opt/etherpad/settings.json

Change the following line:

"authenticationMethod": "${AUTHENTICATION_METHOD:sso}",

into this:

"authenticationMethod": "${AUTHENTICATION_METHOD:apikey}",

Restart etherpad, and the <code>APIKEY.txt</code> should be generated again.

# systemctl restart etherpad

Copy the key and save it somewhere temporary.

===Step 4: configure octomode===

To configure octomode, save the following configuration settings as to a file called <code>.env</code>.

<pre>
OCTOMODE_APPLICATION_ROOT=XXX
OCTOMODE_PORTNUMBER=XXX
OCTOMODE_PAD_URL=XXX
OCTOMODE_PAD_API_URL=XXX
OCTOMODE_PAD_API_KEY=XXX
</pre>

# cd /opt/octomode/
# nano .env

* '''OCTOMODE_PAD_API_KEY''': ''required'', '''no default'''
* '''OCTOMODE_APPLICATION_ROOT''': ''optional'', default: <code>/</code>
* '''OCTOMODE_PORTNUMBER''': ''optional'', default: <code>5001</code>
* '''OCTOMODE_PAD_URL''': ''required'', default: <code>https://cc.practices.tools/pad/</code> (you need API access to this pad instance)
* '''OCTOMODE_PAD_API_URL''': ''required'', default: <code>https://cc.practices.tools/pad/api/1.2.15/</code>

'''Note''': you must provide a value for <code>OCTOMODE_PAD_API_KEY</code>, <code>OCTOMODE_PAD_URL</code> and <code>OCTOMODE_PAD_API_URL</code>.

You can also change the “PORTNUMBER”, this is the port at which octomode will be running. You can change it to any port number that is not used yet on the server.

Close and save the <code>.env</code> file with <code>CTRL+X</code>, <code>Y</code>, <code>ENTER</code>.

===Step 5: Install the dependencies that octomode uses===

First make sure that <code>pip3</code> and <code>pandoc</code> is installed.

On debian you can install it by running:

# apt install python3-venv pandoc

There is a Makefile in the octomode folder, which can be used to install the dependencies.

First navigate to the octomode folder and then run:

# cd /opt/octomode
# make setup

Change the ownership of the installed dependencies to octomode.

# chown -R octomode:octomode .venv

===Step 6: Try to run octomode, to see if it works!===

# make local

If you are currently in the same local network as rosa, you can visit rosa’s ip address on port 5001.

http://192.168.178.58:5001

It could be, that the etherpads in the iframes are blocked because of a cross-site header...

If you are trying to use an etherpad that runs on the same server, try to switch your <code>.env</code> settings to the same ip-adress or domain name.

Try to visit all the different “modes”: <code>pad</code>, <code>stylesheet</code>, <code>html</code> and <code>pdf</code>, to make sure that they all work.

You can stop the application with <code>CTRL+C</code>.

===Step 7: Run octomode as a background service===

Octomode is written in Flask, a python library to make web applications. It needs to run all the time in order to be available for people to use. We will make a systemd <code>.service</code> file for this. https://blog.miguelgrinberg.com/post/running-a-flask-application-as-a-service-with-systemd

Make a <code>.service</code> file for octomode:

# nano /etc/systemd/system/octomode.service

Paste the following configurations in the file:

<pre>
[Unit]
Description=Collective PDF rendering environment After=network.target

[Service]
User=octomode
WorkingDirectory=/opt/octomode
ExecStart=make local
Restart=always

[Install]
WantedBy=multi-user.target
</pre>

Reload the systemd daemon:

# systemctl daemon-reload

Enable octomode as a service:

# systemctl enable octomode

And start the octomode service.

# systemctl start octomode

Check if it works by visiting http://192.168.178.58:5001/ again!

===Step 8: Connect octomode to an URL===

To access octomode through an URL, like https://rosa.vvvvvvaria.org/octomode/, a mapping is needed to route octomode’s port 5001 to the URL that will be used. In nginx, we can use a proxy_jump for this.

Open the nginx configuration file.

# cd /etc/nginx/sites-enabled
# nano default

Add the following setting to the nginx file.

<pre>
location /octomode {
proxy_pass http://127.0.0.1:5001;
auth_basic "Hello! This is the CC version of octomode, octomode-as-a-service for a trusted peers-to-peers network.";
auth_basic_user_file /etc/nginx/.htpasswd;
}
# Serve the /static/ folder nginx (instead of Flask)
# as this Flask installation runs outside the root URL
location ^~ /static/ {
alias /opt/octomode/static/;
autoindex off;
}
</pre>

At CC we share a password between a trusted peers-to-peers network, which you have to generate to make above configurations with the <code>auth_basic</code> settings work.

For this, you can follow: https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/

Change the permissions of the <code>/opt/octomode/static/</code> folder, as this folder will be served by nginx.

# chown -R www-data:www-data /opt/octomode/static/
# chmod -R g+w /opt/octomode/static/

Check if you configuarion is oke.

# nginx -t

If so, then reload nginx.

# systemctl reload nginx

To test it, run:

# make action

This will first check if you already install gunicorn in the .venv folder, and after that run octomode with gunicorn and not the built-in Flask dev server.

And lastly, change your systemd background service file, to switch to <code>make action</code>:

# nano /etc/systemd/system/octomode.service

<pre>
[Unit]
Description=Collective PDF rendering environment After=network.target

[Service]
User=octomode
WorkingDirectory=/opt/octomode
ExecStart=make action
Restart=always

[Install]
WantedBy=multi-user.target
</pre>

See if it works by visiting http://192.168.178.58/octomode/ or https://rosa.vvvvvvaria.org/octomode/.

==Octomode default templates==

===PAD.md===

<pre>
---
title: octomode
language: en
---





<section id="cover">
# *in octomode* { #title }

</section>

<section id="main">
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.

```
Edit this text in the PAD view.
Edit the styling in the STYLESHEET view.
Preview the page in the HTML view.
Render it on pages in the PDF view.
```

</section>
</pre>

===PAD.css===

<pre>
@charset "utf-8";

@page{
size: A5;
margin: 10mm 20mm 25mm 20mm;

@bottom-center{
content: counter(page);
font-family: monospace;
}
}
body{
font-size: 12px;
line-height: 1.5;
color: #822b01;
}

/* ------------------------------------ cover */

@page:first{
background-color: #f3c6ff;
color: #822b01;
}
section#cover{
break-after: always;
}
section#cover h1#title{
font-size: 300%;
}

/* ------------------------------------ main */

section#main pre{
color: magenta;
}
</pre>

Installing octomode - Revision history

Manetta: /* How to install octomode? */