Skip to content

System checks

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

Info

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

Info

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_KEY
  • AWS_SECRET_KEY
  • AWS_THUMBNAIL_BUCKET
  • AWS_STAGING_BUCKET
  • AWS_EXPORT_BUCKET

The 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.

arkindex.E012

The Docker images specified for workers providing features in `update_system_workers` have not been verified as up to date for Arkindex version […].

The arkindex update_system_workers command relies on Arkindex developers manually setting the recommended Docker images for each feature so that it can automatically configure them. When attempting to release a new Arkindex version without confirming that the images are up to date, this error can occur. This error should never be raised while deploying to production, since it should have prevented releasing Arkindex in the first place.

Before releasing a new version of Arkindex, developers should check the FEATURE_IMAGES constant under arkindex.process.management.commands.update_system_workers. If the recommended releases of each worker has changed, the tags in this constant must be updated.

Once this check is completed, the VALID_VERSION constant may be set to the current Arkindex version to confirm that the FEATURE_IMAGES have been checked for this version. Updating this value will resolve this system check error.

Warnings

Info

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.

Since Arkindex 1.6.3, this check only runs when the ingest feature flag is enabled.

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_CONFIG

The 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.

There is no worker version available to initialize elements.
This worker version is required to initialize elements when running a process on Arkindex.
Starting or retrying processes will fail.
        HINT: Run `arkindex update_system_workers` or set a worker version's `feature` to `init_elements`.

Starting with Arkindex 1.6.3, running processes on elements requires a worker version whose feature attribute is set to init_elements. This worker version will be executed at the beginning of each process to distribute the process elements to the worker versions selected by the user, splitting them into chunks as necessary. The arkindex update_system_workers command can automatically create or update the necessary worker type, worker and worker version to provide this feature. Alternatively, instance administrators can use the administration interface to manually create or update a worker version with the specified feature.

On Arkindex 1.6.1 and 1.6.2, the following warning was shown instead:

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.

The docker.init_elements_image setting, which defaulted to registry.gitlab.teklia.com/arkindex/workers/init-elements:latest, pointed the Arkindex backend to the worker version used in processes to distribute the process elements to the workers and eventual chunks.

arkindex.W015

Since Arkindex 1.6.2.

There is no worker version available to import elements from S3.
Starting or retrying S3 import processes will fail.
        HINT: Run `arkindex update_system_workers` or set a worker version's `feature` to `s3_ingest`.

Starting with Arkindex 1.6.3, importing from S3 requires a worker version whose feature attribute is set to s3_ingest. This worker version will be responsible for running the import. The arkindex update_system_workers command can automatically create or update the necessary worker type, worker and worker version to provide this feature. Alternatively, instance administrators can use the administration interface to manually create or update a worker version with the specified feature.

This warning will only appear when the ingest feature flag is enabled.

In Arkindex 1.6.2, the following warning was shown instead:

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.

The docker.ingest_image setting pointed the Arkindex backend to the worker version used in S3 import processes.