The provided docker-compose creates three containers:
- Database (based on mariadb:10)
- OpenXPKI Server
- OpenXPKI WebUI
Before running compose you MUST place a configuration directory named openxpki-config
in the current directory, the easiest way is to clone the branch community
from the openxpki-config
repository at github.
$ git clone https://github.com/openxpki/openxpki-config.git \
--single-branch --branch=community
The default configuration expects the database to be available at server startup which might not be the case when using docker, especially on the first start when the database needs to be created. To avoid the server to crash when the database is not available you should set wait_on_init
in config.d/system/database.yaml
. For a production setup you should place this into your main configuration but for a test drive you can use the provided overlay file:
# Create config overlay file to let OpenXPKI wait for the database
$ cp contrib/wait_on_init.yaml openxpki-config/config.d/system/local.yaml
Now run docker-compose:
$ docker-compose up
# provisioning takes about a minute and you will see some warnings while
# OpenXPKI waits for the database, before you proceed please wait until you see
openxpki-server_1 | Binding to UNIX socket file "/var/openxpki/openxpki.socket"
openxpki-server_1 | Group Not Defined. Defaulting to EGID '0'
openxpki-server_1 | User Not Defined. Defaulting to EUID '0'
openxpki-server_1 | Setting gid to "102"
openxpki-server_1 | Setting uid to "101"
In case you have make
installed you can also just run make compose
which does all the above for you.
If you don't provide a TLS certificate for the webserver yourself (see below), the init script creates a self-signed one and exposes the webserver UI on port 8443 (https://localhost:8443/openxpki/
). The SCEP interface is available via plain HTTP on port 8080 (http://localhost:8080
).
The system is started with the configuration found in the openxpki-config path, but without any tokens installed! Place your keys and certificates into the ca
directory of the config directory and follow the instructions given in the quickstart tutorial: https://openxpki.readthedocs.io/en/latest/quickstart.html#setup-base-certificates (there is also a helper script for importing the keys, see below).
If you want to setup a two-tier hierarchy we recommend using our command line ca tool clca
(https://github.com/openxpki/clca).
The repository comes with a bootstrap script, that generates a two-tier PKI hierarchy and prepares anything "ready-to-go".
$ docker exec -it openxpki_openxpki-server_1 /bin/bash /etc/openxpki/contrib/sampleconfig.sh
If you have make
installed, just run make sample-config
which will run the above command for you.
In case the WebUI does not start or you get a 500 Server Error when calling the RPC/SCEP/EST wrappers the most common problem are broken permissions on the log folder/files /var/log/openxpki
. Running docker exec -ti openxpki_openxpki-client_1 chmod 4777 /var/log/openxpki
will make the folder world writable so the problem should be gone.
Some distros, e.g. CentOS/RHEL, have SELinux enabled by default which will likely prevent the docker container to read the mounted config volume. You can work around this by adding a :z
to the volume path in the docker-compose.yml - please read moby/moby#30934 before doing so as it can make your system unusable!
volumes:
- ./openxpki-config:/etc/openxpki:z
The sample configuration uses a so called symlink to a template directory to create the "democa". Windows does not support symlinks and when you clone
and mount the repository from a host running windows this configuration is missing. If you get No workflow configuration found for current realm
when starting OpenXPKI try to replace the (broken) symlink in openxpki-config/config.d/realm by a full copy.
Another option is to activate symlink emulation in git, see https://github.com/git-for-windows/git/wiki/Symbolic-Links.
Prebuilt images for the official releases are provided by WhiteRabbitSecurity via a public Docker repository whiterabbitsecurity/openxpki3
.
Those are also used by the docker-compose file.
The Dockerfile creates a container based on Debian Buster using prebuilt deb packages which are downloaded from the OpenXPKI package mirror (https://packages.openxpki.org).
The image has all code components installed but comes without any configuration.
The easiest way to start is to clone the docker
branch from the openxpki-config repository from github https://github.com/openxpki/openxpki-config
and mount it to /etc/openxpki
.
As the container comes without a database engine installed, you must setup a database container yourself and put the connection details into config.d/system/database.yaml
.
The container runs only the OpenXPKI daemon but not the WebUI frontend. You can either start apache inside the container or create a second container from the same image that runs the UI. In this case you must create a shared volume for the communication socket mounted at /var/openxpki/
(this will be changed to (/run/openxpki/
with one of the next releases!).
Start the server container and run setup-cert
to setup the CA certificates and matching keys. The artifacts need to be placed in openxpki-config/ca/[REALM]/
and file names must match one of the following patterns (case insensitive):
root(-XX).crt
for root certificates
ca-signer(-XX).crt
for signer certificates
vault(-XX).crt
for vault certificates
scep(-XX).crt
for vault certificates
The suffix -XX must contain only numbers and is used as generation identifier on import. If the suffix is omitted, the certificate is imported with the next available generation identifier. The corresponding key files must have the same basename with file ending (*.pem), the key file is copied to $alias.pem so it will be found by the default key specification of the sample config (if the file already exists, nothing is copied).
Certificates/keys for data vault can also be placed in openxpki-config/ca/
. Then, the startup script will detect it and create aliases for all realms.
All key files (except for data vault) are stored in the database so make sure all other tokens (e.g. certsign) are configured correctly:
key_store: DATAPOOL
key: "[% ALIAS %]"
Translations are done using gettext. By default the container comes with a file that covers translations of the sample config and the backend. If you need to modify or extend the translations, you must generate your own po file.
Create a folder openxpki-config/i18n/en_US
and place your overrides/extensions in one or muliple files ending with .po
. When you need to update the internal translations, either create a file openxpki-config/i18n/.update
(can be empty) or run update-i18n
inside the client container. The script will merge the contents of contrib/i18n/
with your local extensions, so make sure you update this when you install a new release. You need to restart the client container afterwards to pull in the new translation file.