Installation
APIS-core is a library that allows you to easily build tools to manage prosopographical data. It is not a ready-made software solution that you just deploy and start working. The typical workflow for starting an APIS project is as follows: set up the project, create an ontology customize the functionalities and views, and finally add your data. This section will guide you through the first step.
Prerequisites
APIS needs Python 3.11+.
Installation
Create a project using your favorite package manager:
poetry new foobar-repository
In your project folder, add apis as a dependency (replace RELEASE_VERSION
with the version you want to install):
poetry add git+https://github.com/acdh-oeaw/apis-core-rdf#RELEASE_VERSION
Now remove the generated __init__.py
(because django-admin
wants to be the
one that creates that) and setup your Django project
rm -f foobar_repository/__init__.py
poetry run django-admin startproject foobar_repository .
Now start using your Django project
poetry run ./manage.py runserver
To use the APIS framework in your application, you will need to add the following dependencies to
INSTALLED_APPS
:
INSTALLED_APPS = [
# our main app, containing the ontology (in the `models.py`)
# and our customizations
"sample_project",
# `apis_override_select2js` is a workaround for APIS'
# handling of autocomplete forms. It should be listed
# at the beginning of the list, to make sure the
# files shipped with it are served in precedence.
"apis_override_select2js",
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
# ui stuff used by APIS
"crispy_forms",
"crispy_bootstrap4",
"django_filters",
"django_tables2",
"dal",
"dal_select2",
# REST API
"rest_framework",
# swagger ui generation
"drf_spectacular",
# The APIS apps
"apis_core.core",
"apis_core.generic",
"apis_core.apis_metainfo",
"apis_core.apis_relations",
"apis_core.apis_entities",
# apis_vocabularies is deprecated, but there are
# still migrations depending on it - it will be dropped
# at some point
"apis_core.apis_vocabularies",
# APIS collections provide a collection model similar to
# SKOS collections and allow tagging of content
"apis_core.collections",
# APIS history modules tracks changes of instances over
# time and lets you revert changes
"apis_core.history",
]
Finally, add the APIS urls to your applications URL Dispatcher
urlpatterns = [
path("", include("apis_core.urls", namespace="apis")),
# https://docs.djangoproject.com/en/5.0/topics/auth/default/#module-django.contrib.auth.views
path("accounts/", include("django.contrib.auth.urls")),
# https://docs.djangoproject.com/en/5.0/ref/contrib/admin/#hooking-adminsite-to-urlconf
path("admin/", admin.site.urls),
]
Now you should be ready to roll. Start creating your entities in you apis_ontology/models.py
.
Installation with Docker
This is the recommended way to install APIS on local machines as well as on server infrastructure. For experimenting with APIS you can use the Dockerfile provided in the APIS core library. It allows you to spin up an APIS instance using the sample-project shipped with the APIS core library. To start it fire up a terminal and run
cd path/to/apis-core-rdf
to change to the directory where the Dockerfile is located.docker build -t apis .
to build the APIS image.docker run -p 5000:5000 apis
to start the container.
The APIS instance should now be accessible under http://localhost:5000.
Alternatively you can also use the docker image built for our demo-project. To do so run:
docker run -p 5000:5000 ghcr.io/acdh-oeaw/apis-core-rdf/discworld/main:latest
to start the container.
To use the image for local development you can mount your local APIS instance directory into the container, using the following command: To do so you can use the following command:
docker run -p 5000:5000 -v /path/to/your/apis_instance:/app apis
Please note that you might need to install custom dependencies for the APIS instance in your local docker container.
This container uses the Django development server and is not suitable for production use. Please see the next section for deploying APIS in production.
Docker Compose
In production APIS should be used together with an SQL database. The simplest way to set that up is by using Docker Compose.
Below is an example of a docker-compose.yml
file that sets up an APIS instance with a PostgreSQL database.
version: '3.8'
services:
app:
build:
context: .
dockerfile: Dockerfile
depends_on:
db:
condition: service_healthy
restart: true
environment: # some settings can be overwritten with env variables
- DJANGO_SETTINGS_MODULE=apis.settings
- DJANGO_SECRET_KEY=your_secret_key
- DJANGO_DEBUG=True
- DATABASE_URL=postgres://postgres:postgres@db:5432/postgres
volumes:
- ${PWD}/local_apis_instance:/app #mount your local APIS instance to the container if needed
ports:
- 5000:5000
db:
image: postgres:latest
restart: unless-stopped
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
POSTGRES_USER: postgres
POSTGRES_DB: postgres #use other passwords in production
POSTGRES_PASSWORD: postgres
POSTGRES_EXTENSIONS: pg_trgm
healthcheck:
test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
interval: 10s
timeout: 3s
retries: 3
volumes:
postgres-data:
After docker-compose up
you should now have a default APIS installation accessible under http://127.0.0.1:5000.