Prebuilt images for the official releases are provided by White Rabbit Security via a public Docker repository on DockerHub whiterabbitsecurity/openxpki3. Those are created from the Dockerfile found in this repository.
This repository contains a docker-compose.yml that spawns four containers
- Database (based on mariadb:10)
- OpenXPKI Server
- OpenXPKI Client
- 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=communityThe remainder of this guide is based on an unmodified confguration, if you want to run your adapted configuration you might need to adapt the steps.
The example configuration uses the same passwords as those given in the compose file,
if you change them, also update them in config.d/system/database.yaml.
You MUST configure the session storage driver for the WebUi in
client.d/service/webui/default.yaml by either:
creating the user and permissions on the database as outlined in the QUICKSTART document
or
Disable the database driver to fall back to the file system storage driver
Do NOT use the same credentials as for the backend database as this gives the frontend client full database access which is a security risk! You might deviate from this for a local test run, but you have been warned!
The webserver container maps the folder openxpki-config/tls/ to /etc/openxpki/tls/, the related configuration items are:
SSLCertificateFile /etc/openxpki/tls/endentity/openxpki.crt
SSLCertificateKeyFile /etc/openxpki/tls/private/openxpki.pem
SSLCACertificatePath /etc/openxpki/tls/chain/Place certificate and key in the given places. The chain folder is used to validate incoming TLS Client request, it must in any case hold a single file as the apache does not start otherwise. If you do not provide any files, dummy certificates will be created on first startup.
The old docker-compose (Version 1) is no longer supported, you need a recent version of dockerwith the compose plugin. It should be sufficient to start the web container as this depends on all others so they will also be started:
$ docker compose up -d web
[+] Running 4/4
✔ Container OpenXPKI_Database Healthy 0.5s
✔ Container OpenXPKI_Server Running 0.0s
✔ Container OpenXPKI_Client Running 0.0s
✔ Container OpenXPKI_WebUI Running 0.0s
In case you have make installed you can also just run make compose which does all the above for you.
The system should now be up and running and you can access the WebUI via https://localhost:8443/webui/index/.
You can already have a look around but to issue certificates you need to generate and import your Root and Issuing CA certificates and load them into the system.
To import your own keys and certificates follow the instructions given in the QUICKSTART tutorial. If you want to setup a two-tier hierarchy we recommend using our command line ca tool clca (https://github.com/openxpki/clca).
The default config repository comes with a bootstrap script, that generates a two-tier PKI hierarchy and prepares anything "ready-to-go".
$ docker compose exec -u root -it server /etc/openxpki/contrib/sampleconfig.shIf you have make installed, just run make sample-config which will run the above command for you.
Most likely your session storage driver setup is broken, check the logs of the client container.
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!
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.
