Installing octomode
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 /opt/octomode 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 chroot 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 APIKEY.txt 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 APIKEY.txt 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 .env.
OCTOMODE_APPLICATION_ROOT=XXX OCTOMODE_PORTNUMBER=XXX OCTOMODE_PAD_URL=XXX OCTOMODE_PAD_API_URL=XXX OCTOMODE_PAD_API_KEY=XXX
# cd /opt/octomode/ # nano .env
- OCTOMODE_PAD_API_KEY: required, no default
- OCTOMODE_APPLICATION_ROOT: optional, default:
/ - OCTOMODE_PORTNUMBER: optional, default:
5001 - OCTOMODE_PAD_URL: required, default:
https://cc.practices.tools/pad/(you need API access to this pad instance) - OCTOMODE_PAD_API_URL: required, default:
https://cc.practices.tools/pad/api/1.2.15/
Note: you must provide a value for OCTOMODE_PAD_API_KEY, OCTOMODE_PAD_URL and OCTOMODE_PAD_API_URL.
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 .env file with CTRL+X, Y, ENTER.
Step 5: Install the dependencies that octomode uses
First make sure that pip3 and pandoc 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.
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 .env settings to the same ip-adress or domain name.
Try to visit all the different “modes”: pad, stylesheet, html and pdf, to make sure that they all work.
You can stop the application with CTRL+C.
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 .service file for this. https://blog.miguelgrinberg.com/post/running-a-flask-application-as-a-service-with-systemd
Make a .service file for octomode:
# nano /etc/systemd/system/octomode.service
Paste the following configurations in the file:
[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
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.
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;
}
At CC we share a password between a trusted peers-to-peers network, which you have to generate to make above configurations with the auth_basic 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 /opt/octomode/static/ 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 make action:
# nano /etc/systemd/system/octomode.service
[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
See if it works by visiting http://192.168.178.58/octomode/ or https://rosa.vvvvvvaria.org/octomode/.
Octomode default templates
PAD.md
---
title: octomode
language: en
---
<!--
|
__ __ _|_ __ _ _ _ __ __| _
/ \_/ | / \_/ |/ |/ | / \_/ | |/
\__/ \___/|_/\__/ | | |_/\__/ \_/|_/|__/
This document is opened in octomode.
pad : all materials for the PDF are collected here (written in Markdown)
stylesheet : all CSS rules for the PDF are collected here (written in CSS)
html : render the structure of the lay out as a HTML (with PyPandoc)
[note] this view does not render any styling!
pdf : render the lay out as a PDF (with Paged.js)
https://git.vvvvvvaria.org/cc/octomode
-->
<!--
-------------------------------------------------------------------------------
This pad is hosted by CC (creative crowds), a server that we share for doing
collective research on the entanglements of tools, cultures and infrastructure.
How can this server be available AND unstable, public AND being paid for,
free to be used AND situated, a production environment AND in transformation?
While surfing the contradictions, we are formulting collective guidelines for
engaging with this server, which you can find at: https://cc.practices.tools
-------------------------------------------------------------------------------
-->
<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>
PAD.css
@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;
}