Improve documentation

This commit is contained in:
Jan Dittberner 2020-12-23 06:30:43 +01:00
parent 0c56512174
commit 714533350b

View file

@ -1,6 +1,12 @@
# CAcert local development setup # CAcert local development setup
This repository contains a local development environment setup for the CAcert software. This repository contains a local development environment setup for the CAcert
software.
It runs multiple Docker containers using docker-compose the provide different
parts of the CAcert software. This includes CATS (CAcert automated testing
system), the test manager software and the WebDB software as well as supporting
server components (database, SMTP and IMAP).
## Prerequisites ## Prerequisites
@ -32,21 +38,48 @@ Create a .env file that defines the following variables
Variable | Usage Variable | Usage
--- | --- --- | ---
`MYSQL_ROOT_PASSWORD` | Database root password `CATCHALL_MAILBOX_PASSWORD` | The password of the IMAP mailbox used by the test manager software
`MYSQL_APP_USER` | Database application user
`MYSQL_APP_PASSWORD` | Database application password
`CLIENT_CERT_EMAIL` | email address for client certificate generated by `setup_test_ca.sh` `CLIENT_CERT_EMAIL` | email address for client certificate generated by `setup_test_ca.sh`
`CLIENT_CERT_USERNAME` | user name for client certificate generated by `setup_test_ca.sh` `CLIENT_CERT_EMAIL` | email address that should be included in the test client certificate that is generated in `testca/certs/testclient.crt.pem` and included in `testca/certs/testclient.p12`
`CLIENT_CERT_PASSWORD` | PKCS#12 keystore password for client certificate generated by `setup_test_ca.sh` `CLIENT_CERT_PASSWORD` | PKCS#12 keystore password for client certificate generated by `setup_test_ca.sh`
`CLIENT_CERT_PASSWORD` | password used to encrypt `testca/certs/testclient.p12`
`CLIENT_CERT_USERNAME` | full name for a user that is included in the CN field of the subject distinguished name in the test client certificate
`CLIENT_CERT_USERNAME` | user name for client certificate generated by `setup_test_ca.sh`
`MYSQL_APP_PASSWORD` | Database password for webdb
`MYSQL_APP_USER` | Database user for webdb
`MYSQL_CATS_PASSWORD` | Database password for cats
`MYSQL_CATS_USER` | Database user for cats
`MYSQL_MGR_PASSWORD` | Database password for the test manager
`MYSQL_MGR_USER` | Database user for the test manager
`MYSQL_ROOT_PASSWORD` | Database root password
```shell ```shell
echo -e "MYSQL_ROOT_PASSWORD=$(openssl rand -base64 18)\nMYSQL_APP_USER=cacert_dev\nMYSQL_APP_PASSWORD=$(openssl rand -base64 18)" > .env echo "CATCHALL_MAILBOX_PASSWORD=$(openssl rand -base64 18)
CLIENT_CERT_EMAIL=user@example.org
CLIENT_CERT_PASSWORD=$(openssl rand -base64 18)
CLIENT_CERT_USERNAME="John Doe"
MYSQL_APP_PASSWORD=$(openssl rand -base64 18)
MYSQL_APP_USER=cacert_dev
MYSQL_CATS_PASSWORD=$(openssl rand -base64 18)
MYSQL_CATS_USER=cats
MYSQL_MGR_PASSWORD=$(openssl rand -base64 18)
MYSQL_MGR_USER=cacert_mgr
MYSQL_ROOT_PASSWORD=$(openssl rand -base64 18)" > .env
./setup_test_ca.sh ./setup_test_ca.sh
docker-compose up docker-compose up
``` ```
After these steps you should be able to reach the CAcert application at https://test.cacert.localhost:8443/. After these steps you should be able to reach the CAcert application at
The test manager application is reachable at https://mgr.cacert.localhost:9443/. https://test.cacert.localhost:8443/. The test manager application is reachable
at https://mgr.cacert.localhost:9443/. CATS is reachable at
https://cats.cacert.localhost:7443/. The magic hostname resolution works on
systems using systemd's nss module for host resolution. If you do not have that
on your system you might need a set of entries in your `/etc/hosts` or its
equivalent for your operating system.
A client certificate is created by `setup_test_ca.sh` and is placed in `testca/certs/clientcert.p12` A client certificate is created by `setup_test_ca.sh` and is placed in
which can be imported in a browser to support client certificate authentication. `testca/certs/clientcert.p12` which can be imported in a browser to support
client certificate authentication. You may also wish to add the CA certificates
in `testca/root/ca.crt.pem` and `testca/class3/ca.crt.pem` to your browser's
trusted CA certificate list.