OpenXPKI certificate management in a Docker container.

docker run -p 8443:443 -v <volume>:/etc/openxpki -e <ENV> moonbuggy2000/openxpki:latest

On first run the container will create and initialize a database as specified by the environment (see below), then import an OpenXPKI configuration either from a user-provided customconfig.sh or, failing that, the defaultconfig.sh from this repo. The server should then be accessible via HTTPS.

A realm and the database can be configured through the container environment or in the normal /etc/openxpki/ configuration files. In the latter case, and for any configuration beyond what is described here, refer to the OpenXPKI docs.

Note: Although this image can do much of the OpenXPKI Quickstart process on its own with minimal configuration, it may not be the sort of thing you want done automatically. This image will provide an easy PKI, not necessarily a production-ready PKI.

There are few types of environment variables:

• OXPKI_DB_* - processed at every startup and will take precedence over (and, in fact, overwrite) any configuration in database.yaml if set, on-disk configuration will be used if unset
• OXPKI_DB_ROOT_* - as above but only required if a database needs to be created, and can't be configured in database.yaml, must be via the environment
• OXPKI_SETUP_* - only processed during container initialization (typically at first run) by defaultconfig.sh and do not take precedence over any existing realm configuration files

Valid environment variables are:

• OXPKI_DB_TYPE - database type (accepts: mariadb (default), mysql, postgresql)
• OXPKI_DB_NAME - database name (default: openxpki)
• OXPKI_DB_HOST - database host name or IP
• OXPKI_DB_PORT - database port (default: 3306)
• OXPKI_DB_USER - database user name (default: openxpki)
• OXPKI_DB_PASS - database user password (default: openxpki)
• OXPKI_DB_ROOT_USER - database root user
• OXPKI_DB_ROOT_PASS - database root password
• OXPKI_DB_MAX_RETRIES - database connection attempt limit (default: 30)
• OXPKI_DB_SSLMODE - PostgreSQL SSL mode (default: disable)
• OXPKI_SETUP_REALM - a realm to configure from defaultconfig.sh (default: democa)
• OXPKI_SETUP_CA_DIR - a folder to store cert, key and pass files generated by defaultconfig.sh (default: /etc/openxpki/config.d/realm/${REALM}/ca)
• OXPKI_SETUP_KEY_PASS - set to a password to use for all generated keys, unset for random key generation (default: unset)
• OXPKI_SETUP_RAOP_NAME - RA Operator user name (default: raop)
• OXPKI_SETUP_RAOP_PASS - RA Operator password (default: openxpki)
• OXPKI_SETUP_FQDN - server FQDN for certificates (default: container's hostname)
• OXPKI_SETUP_ROOT_CA_SUBJECT - subject for generated root CA (default: /CN=${REALM} Root CA)
• OXPKI_SETUP_ISSUING_CA_SUBJECT - subject for generated issuing CA (default: /O=${REALM}/OU=PKI/CN=${REALM} Issuing CA)
• OXPKI_DEBUG - set the --debug argument on openxpkictl, see the openxpkictl manpage for details on appropriate values (default: unset)

Initialization occurs via execution of either a user-provided customconfig.sh, or the included /etc/openxpki/defaultconfig.sh script. This occurs when the file /etc/openxpki/.initiated is not found, which usually only happens on a container's first run (if /etc/openxpki is persistent). If you already have a configuration you want to keep then make sure this file is present before starting the container.

A re-initialization on next start can be forced by touching the file /etc/openxpki/.force_init, which is useful if defaultconfig.sh is applied on first run and you later wish to apply your own customconfig.sh, or to re-run defaultconfig.sh if you're playing with container environment variables.

You probably have to delete a realm's folder to successfully re-run an initialization of that realm, defaultconfig.sh will not modify any existing configuration it finds, in most cases. For a clean outcome the database may need to be dropped as well, but this can be skipped if you're testing and don't mind some non-fatal errors in the webUI.

Any customconfig.sh file should be placed at either /import/customconfig.sh or /etc/openxpki/customconfig.sh. If found, it will be run during initialization in preference to the defaultconfig.sh in the image.

The defaultconfig.sh script works much the same as the default OpenXPKI sampleconfig.sh script in the OpenXPKI config repo it is based on, with the following differences:

• allow a realm to be specified via the OXPKI_SETUP_REALM environment variable
• import user-provided certificates from a volume at /import, or generate automatically if not provided
• allow generation of certificates with random key passwords (pass files are stored in OXPKI_SETUP_CA_DIR)
• install with a single Operator account (no test accounts), optionally configured from the environment (using OXPKI_SETUP_RAOP_*)

Further manual configuration will be likely be required, but this should cover much of the OpenXPKI Quickstart using just the container environment and a mounted volume to import certificates.

A volume mounted at /import will be checked by defaultconfig.sh and relevant certificate files, if found, will be copied to the realm's OXPKI_SETUP_CA_DIR and used to initialize the realm. Any required certificates not provided as files will be generated automatically, with passwords governed by OXPKI_SETUP_KEY_PASS.

Relevant files are certificate, request, key and password files, named as follows:

• OpenXPKI_DataVault.(crt|csr|key|pass)
• OpenXPKI_Issuing_CA.(crt|csr|key|pass)
• OpenXPKI_Root_CA.(crt|csr|key|pass)
• OpenXPKI_SCEP_RA.(crt|csr|key|pass)
• OpenXPKI_WebUI.(crt|csr|key|pass)

Files will be ignored when they don't make sense. If a certificate depends on another that was automatically generated then it can't be imported from a file, it needs to be generated and signed appropriately. This means, if you are providing some of these files, the Root CA will very likely need to be among them, as will the Issuing CA if you're providing SCEP RA and WebUI files.

The /import folder is only checked during initialization and the mount can be safely removed once defaultconfig.sh has copied the files to OXPKI_SETUP_CA_DIR.

GitHub: https://github.com/moonbuggy/docker-openxpki

Docker Hub: https://hub.docker.com/r/moonbuggy2000/openxpki

usql-static: https://github.com/moonbuggy/usql-static