When starting up the Arkindex backend, a series of system checks are performed using Django's system check framework. Django's default checks are mostly intended for developers and should not happen on a deployment, but Arkindex adds its own system checks, mostly intended to help spot configuration errors during deployments.
System checks can be run at any time using arkindex check. Some Arkindex-defined system checks are only run with the arkindex runserver command or when the ALL_CHECKS environment variable is set to true, to prevent issues with running other management commands such as migrate.
When running the system checks in an automated deployment context such as an Ansible playbook, we suggest using arkindex check --fail-level=WARNING to ensure that the operator is aware of any failing system check.
Critical errors prevent Arkindex from starting up.
arkindex.C001🔗Arkindex requires Python 3.10 or later.
Arkindex 1.4.1 or later requires Python 3.10 or later to run. Versions 1.1.4 to 1.4.0 required Python 3.8. Previous versions supported Python 3.7.
Errors prevent Arkindex from starting up.
arkindex.E001🔗This API URL is missing a mandatory ending /
An API URL was improperly written in the URL configuration: all API URLs must end with a /, with the exception of URLs ending with a <path:…> parameter.
This error should never be raised when deploying to production, because an incorrectly formed API URL should always be detected earlier, but you might run into it when developing for Arkindex. When an API URL is incorrectly formed, all imports from arkindex.project.api_v1 fail, which makes it impossible to run tests, or migrations, or start up a development instance.
arkindex.E011🔗[…] is missing; all S3-related features will fail.
This error occurs if one of the following five environment variables are not set:
AWS_ACCESS_KEYAWS_SECRET_KEYAWS_THUMBNAIL_BUCKETAWS_STAGING_BUCKETAWS_EXPORT_BUCKETThe line under this error message should indicate which variable is causing this error.
Note that the bucket settings have default values; if this warning gets raised about them, it means a custom configuration has changed them. The other variables are not set by default.
Warnings do not prevent Arkindex from starting up, but they may signal important configuration issues.
arkindex.W006🔗The […] environment variable should be defined to allow API client autoconfiguration in Ponos tasks.
The Arkindex backend sends various environment variables to Ponos tasks to help them authenticate to the API, especially using the API client's autoconfiguration options. The following environment variables are required for the autoconfiguration to work:
ARKINDEX_API_URL: public-facing URL to the API's root (ending with /api/v1/)ARKINDEX_API_CSRF_COOKIE: the name of the CSRF cookie.Those environment variables should be set in the ponos.default_env YAML configuration section. By default, Arkindex will deduce ARKINDEX_API_CSRF_COOKIE from the csrf.cookie_name option, but it is technically possible to override it.
This warning may be raised if one of the variables is unset or null, as this can cause imports and other processes to fail. None of the other variables in ponos.default_env are checked.
arkindex.W007🔗Enterprise Edition only.
Ponos private key at […] not found. Agents will be unable to connect to this server.
Both the backend and the Ponos agents use private keys to exchange data securely. To register themselves to the server, Ponos agents will first try to retrieve the server's public key; if it cannot be loaded, Ponos agents cannot register.
You can control the path of the private key with ponos.private_key in the YAML configuration, or use arkindex generate_private_key [path] to create a new private key and store it in path.
arkindex.W008🔗The public_hostname setting is missing; absolute URLs may not be correctly generated.
The public_hostname option in the YAML configuration tells Arkindex what its public-facing root URL is, for example http://example.com. Arkindex can run without this option, but some URLs sent in APIs or emails that are expected to be absolute might not be.
arkindex.W009🔗Local ImageServer with ID […] does not exist.
Arkindex uses image servers as the notion of an IIIF server. To allow for imports from locally uploaded files, Arkindex requires a local image server, as in a server to which Arkindex can upload images.
You can use the Django admin to create an image server. It must be validated, must not be read_only and must have an S3 bucket. You can then set the image server's ID in the YAML configuration using the local_imageserver_id option.
arkindex.W010🔗INGEST_S3_ACCESS_KEY is not set. S3 ingestion features will fail.
INGEST_S3_SECRET_KEY is not set. S3 ingestion features will fail.
Neither INGEST_S3_REGION nor INGEST_S3_ENDPOINT are set. S3 ingestion features will fail.
One of these messages appears when the ingest.access_key_id, ingest.secret_access_key, ingest.endpoint or ingest.region are not set. The ingestion-related endpoints will cause HTTP 500 errors if those settings are incorrect or missing.
arkindex.W011🔗The […] environment variable is set, and not all S3 settings are set.
This variable might override the Arkindex settings and cause unexpected behavior.
This message appears when not all S3 settings are properly set in the Arkindex configuration, and one or more of the following environment variables is set:
AWS_ACCESS_KEY_ID,AWS_CONFIG_FILE,AWS_CREDENTIAL_FILE,AWS_DEFAULT_PROFILE,AWS_DEFAULT_REGION,AWS_EXECUTION_ENV,AWS_PROFILE,AWS_REGION,AWS_SECRET_ACCESS_KEY,AWS_SECURITY_TOKEN,AWS_SESSION_TOKEN,BOTO_CONFIGThe following message appears instead when not all S3 settings are properly set in the Arkindex configuration, and either one of the ~/.aws/config or the ~/.aws/credentials files exist:
The […] file exists, and not all S3 settings are set.
The settings in this file might override the Arkindex settings and cause unexpected behavior.
When not all S3 settings are fully set in the Arkindex configuration with an access key ID, secret access key and either an endpoint or a region, botocore may use some environment variables or configuration files to fill in the blanks. These variables or configuration files can override the Arkindex settings, causing confusion for developers as some unit tests might fail or behave in unexpected ways, and possible data leaks in production where some credentials might be used unexpectedly.
arkindex.W012🔗Group object with ID […] does not exist.
This warning appears when the SIGNUP_DEFAULT_GROUP ID set in settings does not correspond to an existing Group.
arkindex.W013🔗Since Arkindex 1.6.1.
Defining a default value for the ARKINDEX_API_TOKEN variable may introduce a security issue by allowing Ponos tasks to bypass the Ponos task authentication. Consider removing it.
The ARKINDEX_TASK_TOKEN environment variable is automatically set when starting processes to allow all tasks to authenticate as the creator of the process. In earlier versions of Arkindex, the ARKINDEX_API_TOKEN needed to be defined in the Ponos default variables configuration to provide an instance-wide API token, which usually was given unrestricted access to all projects. This warning has been introduced to discourage instance administrators from giving administrator access to all tasks in all processes, and have their tasks use the ARKINDEX_TASK_TOKEN instead.
arkindex.W014🔗Since Arkindex 1.6.1.
Worker version with Docker image […] does not exist / is not in the Available state.
This worker version is required to initialize elements when running a process on Arkindex.
Starting or retrying processes will fail.
Starting with Arkindex 1.6.1, the docker.init_elements_image setting, which defaults to registry.gitlab.teklia.com/arkindex/workers/init-elements:latest, points the Arkindex backend to the worker version used in processes to distribute the process elements to the workers and eventual chunks. The version using that Docker image must exist on the Arkindex instance, and be available.
arkindex.W015🔗Since Arkindex 1.6.2.
Worker version with Docker image […] does not exist / is not in the Available state.
This worker version is required to import from S3 on Arkindex.
Starting or retrying S3 import processes will fail.
Starting with Arkindex 1.6.2, the docker.ingest_image setting points the Arkindex backend to the worker version used in S3 import processes. The version using that Docker image must exist on the Arkindex instance, and be available.