gu-gridh / arosenius-api

The Ivar Arosenius archive backend

Here is the source code for the backend for the Ivar Arosenius online archive (http://aroseniusarkivet.org).

The frontend can be found here: https://github.com/CDH-DevTeam/arosenius-archive-gui

The admin system for the database can be found here: https://github.com/CDH-DevTeam/arosenius-admin

This documentation also addresses server requirements and server setup.

Requirements

• MySQL (5.7, other versions may also work)
• Node.js (12.18, other versions may also work)
• GraphicsMagick

The API runs on port 3010 by default, but this can be overridden in config.

Getting started

To run the backend, first clone the repository or your own fork of it. Then install all JS dependencies, create config files and start it.

git clone https://github.com/CDH-DevTeam/arosenius-api.git
cd arosenius-api
npm install
cp config.demo.js config.js
cp users.demo.js users.js
# Edit config.js and users.js
node app.js

During development, you can use nodemon to have the server restart whenever any source file is changed:

npm --global install nodemon
nodemon app.js

Documentation

The ApiDoc documentation in documentation/ is very incomplete and oudated. Improve it or ignore it.

Images

Images are handled through the IMGR framework via Express.js. It requires GraphicsMagick (gm).

The server can serve images in an arbitrary resolution which is defined in the url. For example, the image 1.jpg can be accessed in full resolution via [url]/images/1.jpg and in max 1600px resolution via the url [url]/images/1600x/1.jpg

Original images are read from the directory specified by image_path in the config. It can be an absolute or a relative path. When using the resizing urls, the resulting resized images are stored in the directory specified by image_temp_path as a cache. Note that there is no cleanup or expiry mechanism of resized images, nor any restriction on what sizes can be requested.

Users

Users are defined in the users.js file. All users have the same privileges.

Data model

The data model for this project began as an Elasticsearch index, before it was converted to MySQL in 2020. The data structure is still artwork-document-centered, and some other design choices in the model and code are due to this Elasticsearch legacy.

Migrating from Elasticsearch to MySQL

Consider this as documentation for a one-shot operation in the past.

1. Run npm install to get new dependencies
2. Run elasticdump on the server and scp it to ./arosenius_v4.json
3. Create a MySQL database locally
   • Make sure to use DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_swedish_ci (see https://mariadb.com/kb/en/setting-character-sets-and-collations/)
4. Extend config.js with the mysql.* properties (see config.demo.js)
5. Run the data migration:
   • Run the SQL commands in arosenius-model.sql to delete (!) and create necessary tables.
   • Run node es-to-mysql.js
   • Inspect the MySQL database
   • Improve the script and arosenius-model.sql
   • Repeat

Adapting to custom data

This database backend is open source, and we encourage you to use it for your own data. If you do, we also recommend using arosenius-archive-gui as a user-friendly GUI and arosenius-admin for manually managing data entries.

As the data model is quite hard-coded into the code, this requires that you can either structure your data into the same model, or edit the code to fit your data better. See arosenius-model.sql for the SQL definition of the data model (schema).