Getting Started With Ourchive

The below step-by-step guide assumes you have Ubuntu 22.04 installed on a VPS. This is the most straightforward way to run Ourchive with the existing code. Docker or a managed environment (such as DigitalOcean's App Platform or Python Anywhere) can also be used, but are beyond the scope of this guide.

Dependencies

1. Domain: you should have a domain registered and associated with a server.
2. VPS configuration: Your VPS should be running Ubuntu 22.04, Nginx should be installed, and you should have a firewall configured to allow Nginx secure traffic.
3. Email: Ourchive can be used without an email provider, but as the admin, you would need to monitor reports and invite requests carefully.
   
   Ourchive supports use of a third-party library which integrates Django and Mailgun. Mailgun has a free tier that would be suitable for the extremely limited numbers of emails the platform sends.
   
   You can also use Amazon SES, which is supported out of the box with Django. If you are using Amazon SES, you'll need to update settings.py. Because this is an out of the box Django capability, we do not document precise configuration, but there are many setup guides online.
   
   If you have send-only email configured on your server, you can configure settings.py to use this email. Doing so is beyond the scope of this guide.
4. Captcha: Ourchive integrates with HCaptcha. Using Captcha is strongly recommended to prevent spam. You can sign up for a free account; you will enter your credentials while configuring Ourchive's secrets.

Installation

Prerequisites

SSH into your VPS as a user with sudo permissions.

If you haven't done so, create an ourchive user:

# create ourchive user
sudo adduser --disabled-login ourchive

As your sudoer, install prerequisite software:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install python3.11 python3-pip python3-dev libpq-dev postgresql postgresql-contrib nginx python3.10-venv ffmpeg vim certbot python3-certbot-nginx

Configure Postgres. Be sure to update the password.

# start the service
sudo systemctl start postgresql.service

# log into postgres
sudo -u postgres psql

# create database and user. NOTE: the below assumes you are using Postgres version 15 or higher.

# create the database
CREATE DATABASE ourchive_db;

# create the Ourchive user. This should match the information in settings.py.
CREATE USER ourchive WITH PASSWORD '[CHANGEME]';

# grant privileges to the ourchive user
GRANT ALL PRIVILEGES ON DATABASE ourchive_db TO ourchive;

# connect to the db
\c ourchive_db postgres

# schema permissions & locale
GRANT ALL ON SCHEMA public TO ourchive;
ALTER ROLE ourchive SET client_encoding TO 'utf8';
ALTER ROLE ourchive SET default_transaction_isolation TO 'read committed';
ALTER ROLE ourchive SET timezone TO 'UTC';

# install trigram search extension
CREATE EXTENSION pg_trgm;

Switch to your Ourchive user and start setting up the Django project:

# the below should all be done as your ourchive user
su - ourchive

# the home directory for your ourchive user
cd /home/ourchive/

# clone the repo
git clone -b production https://github.com/c-e-p/ourchive.git && cd ourchive

# create & activate virtual environment
python3 -m venv virtualenv
source virtualenv/bin/activate

# install server dependencies
pip install gunicorn
pip install gevent
cd ourchive_app && pip install -r requirements.txt && pip install -r importer_requirements.txt

Secrets

Next, you'll want to update the default application secrets. Ourchive uses python-dotenv for environment variables. The below steps demonstrate how to open the .env file for modification. Prior to doing so, please review each variable so you understand what you need to update.

# navigate to core app directory
cd ourchive_app

# copy the sample environment file to make your modifications
cp .env.sample .env

# open your env file for modifications
vim .env

• OURCHIVE_SECRET_KEY: this is the secret key for your app. Generate a long, strong, random series of characters. You can use a password manager to create one for you.
• OURCHIVE_DB_PW: This is the password for your ourchive Postgres user, the same password you set while installing Postres.
• OURCHIVE_DEBUG: In production this should be set to False.
• OURCHIVE_DEV: In production this should be set to False.
• OURCHIVE_MEDIA_ROOT: The root folder for storing media. The default value assumes a volume mounted as ourchive-volume to the root mnt folder in Ubuntu: /mnt/ourchive-volume/media.
• OURCHIVE_MEDIA_URL: The media URL for serving media. This should be consistent with the media URL you later configure in Nginx. Default value: /media/.
• OURCHIVE_TMP_ROOT: The root directory for temporary files, such as /tmp/.
• OURCHIVE_CAPTCHA_SITE_KEY: The site key provided by hCaptcha.
• OURCHIVE_USE_CAPTCHA: We recommend leaving this as True.
• OURCHIVE_CAPTCHA_PROVIDER: Do not change.
• OURCHIVE_CAPTCHA_PARAM: Do not change.
• OURCHIVE_CAPTCHA_SECRET: The secret key provided by hCaptcha.
• OURCHIVE_DB_HOST: If you followed setup instructions for Postgres, your host is 'localhost'; if not, your host is whatever Postgres says.
• OURCHIVE_ROOT_URL: Your domain URL without the protocol, e.g. ourchive.io.
• OURCHIVE_SERVER_IP: The IP address of your server. Used as part of ALLOWED_HOSTS, to allow for internal server traffic.
• OURCHIVE_SERVER_EMAIL: The email address you want to use to receive admin messages from Ourchive.
• OURCHIVE_DEFAULT_FROM_EMAIL: Your admin email; should be consistent with the 'from' email set up in Mailgun.
• OURCHIVE_LOG_LEVEL: Controls Django log level. Default is WARNING.

If you are using Mailgun, the following secrets should be configured.

• OURCHIVE_MAILGUN_API_KEY: You will need to set up an API key within Mailgun for Ourchive to use. Once you've created the API key, put it in your .env file. The app will then use this API key for sending e-mails to your users.
• OURCHIVE_MAILGUN_SENDER_DOMAIN: The domain configured as part of Mailgun setup; typically something like mail.ourchive.io.

Django Configuration

Now we are going to configure the site itself. First we migrate our database:

# navigate one directory up, to manage.py
cd ../
python manage.py migrate

Next, we want to load the default data.

python manage.py loadourchivedata

Create your admin user. This is a website user that also has access to the Django admin backend.

# follow the prompts to finish creating your user
python manage.py createsuperuser

Finally, process static files.

python manage.py collectstatic

Service Setup

Ourchive will use two services. The first is Gunicorn, which will handle requests passed from Nginx. (This approach was developed using DigitalOcean's guide as a reference.)

The second is an apscheduler service that will handle batch jobs such as work imports.

Gunicorn

Switch back to your SSH sudoer (the user you SSH'd into the VPS with). Then, create a service file that instructs your server on how to run Ourchive using Gunicorn.

sudo vim /etc/systemd/system/gunicorn.service

Populate the gunicorn.service file with the below text:

# the contents of gunicorn.service

[Unit]
Description=gunicorn daemon
After=network.target

[Service]
User=ourchive
Group=www-data
WorkingDirectory=/home/ourchive/ourchive/ourchive_app
ExecStart=/home/ourchive/ourchive/virtualenv/bin/gunicorn --log-file /home/ourchive/ourchive/gunicorn_log.log --log-level warn -k gevent --workers 3 --timeout 600 --bind unix:/home/ourchive/ourchive/ourchive_app/ourchive_app.sock ourchive_app.wsgi:application

[Install]
WantedBy=multi-user.target

Start the service, and enable it so that it starts on server start-up:

sudo systemctl start gunicorn
sudo systemctl enable gunicorn

APScheduler

Ourchive uses APScheduler for periodic tasks. Like Gunicorn, first you'll open the file, then you'll populate it with the service information.

sudo vim /etc/systemd/system/apscheduler.service

Populate the apscheduler.service file with the below text:

[Unit]
Description=apscheduler daemon
After=network.target

[Service]
User=ourchive
Group=www-data
WorkingDirectory=/home/ourchive/ourchive/ourchive_app
ExecStart=/home/ourchive/ourchive/virtualenv/bin/python /home/ourchive/ourchive/ourchive_app/manage.py runapscheduler

[Install]
WantedBy=multi-user.target

Start the service, and enable it so that it starts on server start-up:

sudo systemctl start apscheduler
sudo systemctl enable apscheduler

Server Setup

Finally, you'll want to configure Nginx, including certbot.

First, open the sample nginx config file and replace [CHANGEME] with your server name, such as ourchive.io:

# open the file. server_name is on line 4.
vim /home/ourchive/ourchive/ourchive_app/conf/ourchive

# copy the sample nginx config file to the default directory
cp /home/ourchive/ourchive/ourchive_app/conf/ourchive /etc/nginx/sites-available/ourchive

# ensure the ourchive user owns your mounted volume. if you didn't mount a volume, this will look different.
sudo chown -R ourchive:ourchive /mnt/ourchive-volume/*

# symblink your nginx config file to sites-enabled
sudo ln -s /etc/nginx/sites-available/ourchive /etc/nginx/sites-enabled

# test your nginx configuration
sudo nginx -t

# set up certbot for your domain
sudo certbot --nginx -d  [CHANGEME - your domain, for example ourchive.io]

# ensure directory permissions are correct
find /home/ourchive -type d -exec chmod 755 {} \;
namei -nom /home/ourchive/ourchive/ourchive_app/ourchive_app.sock

Configuration

At this point you should have a working site. Congratulations! You can navigate to the admin panel to explore your settings or set up content pages. Or, you can just get busy creating.

Troubleshooting

CSRF Origin Checking Failure

If you encounter a CSRF origin check failure when creating or modifying a work, try adding your site (e.g. example.org) to the CSRF_TRUSTED_ORIGINS array in ourchive_app/ourchive_app/settings/base.py:

CSRF_TRUSTED_ORIGINS = [
    "http://127.0.0.1:8000",
    "http://example.org",
    "https://example.org",
]

Chive Creation Fails, No CORS or CSRF error

If you encounter other issues related to POST requests failing, we recommend trying the mitigation in this GitHub issue.

Other Issues

If something else goes wrong with your install, we recommend reviewing the details: did you use the same username and path as the guide? Are you on the same Ubuntu version? etc. If that plus googling the error doesn't fix it, you can contact us.