Some knowledge about package installation, web server and database configuration will be needed.
This software was developed and tested on Linux/Debian 13.2 (codename "trixie") and the easiest way to install would be on a Debian 13.2 system following these instructions.
Another (experimental) way to install it would be via Docker. For more information take a look at the end of this document.
It may also work on other Linux distributions or even non Linux systems with using the requirements.txt, but substantially more knowledge about server administration would be needed.
Feel free to also consult our own documentation that we are using to set up Debian servers for OpenAtlas installations.
- Requirements
- IIIF (optional)
- Tests (optional)
sudo apt install python3 python3-flask python3-psycopg2 python3-flask-babel python3-flask-login
sudo apt install python3-jwt python3-python-flask-jwt-extended python3-flaskext.wtf python3-flask-cors
sudo apt install python3-rdflib python3-shapely python3-flasgger python3-flask-restful python3-pandas
sudo apt install python3-validators python3-email-validator python3-wand python3-svgwrite python3-fuzzywuzzy
sudo apt install python3-xmltodict python3-markdown exiftran python3-bcrypt python3-dateutil p7zip-full
sudo apt install python3-requests python3-bs4 python3-unidecode python3-lxml python3-unidecode python3-numpy
sudo apt install apache2 libapache2-mod-wsgi-py3 gettext npm
sudo apt install postgresql postgresql-17-postgis-3
Copy the files to /var/www/your_site_name or clone OpenAtlas from GitHub and adapt them accordingly as regular user:
git clone https://github.com/craws/OpenAtlas.git
Execute this lines as regular user too:
cd openatlas/static
npm install
Executed statements below as postgres user.
Create an openatlas database user
createuser openatlas -P
Create an openatlas database, make openatlas the owner of it
createdb openatlas -O openatlas
Add the PostGIS and unaccent extension to the database
psql openatlas -c "CREATE EXTENSION postgis; CREATE EXTENSION unaccent;"
Import the SQL files:
cd install
cat 1_structure.sql 2_data_model.sql 3_data_web.sql 4_data_type.sql | psql -d openatlas -f -
Copy instance/example_production.py to instance/production.py
cp instance/example_production.py instance/production.py
Add/change values as appropriate. See config.py which settings are available.
As root copy and adapt install/example_apache.conf for a new vhost, activate the site:
sudo a2ensite your_sitename
Test Apache configuration and restart
sudo apache2ctl configtest
sudo service apache2 restart
Make the files directory writable for the Apache user, e.g.:
sudo chown -R www-data files
First step after a new installation will be visiting the site in your browser and create an admin account, which you should do immediately. You may want to check the admin area to set up default site settings, email (important for password resets) and similar.
If you later like to upgrade the application be sure to read and follow the upgrade instructions.
You don't need this to run the application, but it will improve server side security if running an online productive instance.
Use certbot to create a https vhost.
After Apache is configured to use HTTPS only, add this line to instance/production.py:
SESSION_COOKIE_SECURE = True
IIIF is a set of open standards for delivering high-quality, attributed digital objects online at scale. Be aware that:
- IIIF is optional for an OpenAtlas installation
- Although already working and in use we still consider it experimental
- Enabling IIIF can expose files to the public (without login)
sudo apt install iipimage-server
sudo a2enmod fcgid
sudo service apache2 restart
You can test http://your.server/iipsrv/iipsrv.fcgi to see if it runs.
sudo mkdir /var/www/iipsrv
sudo cp -p /usr/lib/iipimage-server/iipsrv.fcgi /var/www/iipsrv/
sudo chown -R www-data /var/www/iipsrv
Edit the configuration to your needs, see example at install/iipsrv.conf and restart Apache:
sudo vim /etc/apache2/mods-available/iipsrv.conf
sudo service apache2 restart
If using Debian, prevent systemd to try to start the service itself:
sudo systemctl disable iipsrv.service
Further configuration can be done at the IIIF tab in the admin area of the web application.
Install required packages:
sudo apt install python3-coverage python3-pytest python3-pytest-cov
As postgres:
createdb openatlas_test -O openatlas
psql openatlas_test -c "CREATE EXTENSION postgis; CREATE EXTENSION unaccent;"
Copy instance/example_testing.py to instance/testing.py and adapt as needed:
cp instance/example_testing.py instance/testing.py
Create a own folder to test IIIF images, e.g.:
mkdir /var/www/iipsrv/tests
Run tests with coverage
pytest
A Docker setup is available for local development. Please follow the detailed Docker installation instructions here.