From d0630a4c27c17e5c386d7eab8b7d961bf6987752 Mon Sep 17 00:00:00 2001 From: Scott Koranda Date: Tue, 20 Jun 2017 06:29:49 -0500 Subject: [PATCH] Better Docker stack documentation Better Docker stack documentation and removed old documentation for compose and stacks. --- comanage-registry-compose/README.md | 43 --- ...egistry-shibboleth-sp-postgres-compose.yml | 65 ---- comanage-registry-stack/README.md | 43 --- ...egistry-mod-auth-openidc-mariadb-stack.yml | 104 ------- docs/mod-auth-oidc-mariadb-stacks.md | 278 ++++++++++++++++++ .../README.md | 146 --------- 6 files changed, 278 insertions(+), 401 deletions(-) delete mode 100644 comanage-registry-compose/README.md delete mode 100644 comanage-registry-compose/comanage-registry-shibboleth-sp-postgres-compose.yml delete mode 100644 comanage-registry-stack/README.md delete mode 100644 comanage-registry-stack/comanage-registry-mod-auth-openidc-mariadb-stack.yml create mode 100644 docs/mod-auth-oidc-mariadb-stacks.md delete mode 100644 recipes/production-mod-auth-openidc-mariadb/README.md diff --git a/comanage-registry-compose/README.md b/comanage-registry-compose/README.md deleted file mode 100644 index 928c741..0000000 --- a/comanage-registry-compose/README.md +++ /dev/null @@ -1,43 +0,0 @@ - - -# Docker compose for COmanage Registry - -This is an example docker-compose file to deploy COmanage -Registry with the Shibboleth SP -for authentication, PostgreSQL database, and OpenLDAP -slapd using docker-compose (as opposed to Docker stack). - -See the individual image Dockerfile templates and README -files for details on how to inject -necessary deployment details and secrets. - -## Deploy - -``` -docker-compose --compose-file comanage-registry-shibboleth-sp-postgres-compose.yml up -d -``` - -## Tear Down - -``` -docker-compose --compose-file comanage-registry-shibboleth-sp-postgres-compose.yml down -``` diff --git a/comanage-registry-compose/comanage-registry-shibboleth-sp-postgres-compose.yml b/comanage-registry-compose/comanage-registry-shibboleth-sp-postgres-compose.yml deleted file mode 100644 index 7dd768f..0000000 --- a/comanage-registry-compose/comanage-registry-shibboleth-sp-postgres-compose.yml +++ /dev/null @@ -1,65 +0,0 @@ -version: '3.1' - -services: - - comanage-registry-database: - image: comanage-registry-postgres - volumes: - - /opt/comanage-registry-deployment/postgres-data:/var/lib/postgresql/data - - /opt/comanage-registry-deployment/secrets:/run/secrets - environment: - - POSTGRES_USER=postgres - - POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password - - COMANAGE_REGISTRY_POSTGRES_DATABASE=registry - - COMANAGE_REGISTRY_POSTGRES_USER=registry_user - - COMANAGE_REGISTRY_POSTGRES_USER_PASSWORD_FILE=/run/secrets/comanage_registry_postgres_user_password - - comanage-registry-ldap: - image: comanage-registry-slapd - volumes: - - /opt/comanage-registry-deployment/slapd-data:/var/lib/ldap - - /opt/comanage-registry-deployment/slapd-config:/etc/ldap/slapd.d - - /opt/comanage-registry-deployment/secrets:/run/secrets - environment: - - SLAPD_CERT_FILE=/run/secrets/slapd_cert_file - - SLAPD_PRIVKEY_FILE=/run/secrets/slapd_privkey_file - - SLAPD_CHAIN_FILE=/run/secrets/slapd_chain_file - - OLC_ROOT_PW_FILE=/run/secrets/olc_root_pw - - OLC_SUFFIX=dc=my,dc=org - - OLC_ROOT_DN=cn=admin,dc=my,dc=org - ports: - - "636:636" - - "389:389" - - comanage-registry: - image: comanage-registry:hotfix-2.0.x-shibboleth-sp - volumes: - - /opt/comanage-registry-deployment/secrets:/run/secrets - environment: - - COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=Karel - - COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=Novak - - COMANAGE_REGISTRY_ADMIN_USERNAME=karel.novak@my.org - - COMANAGE_REGISTRY_DATASOURCE=Database/Postgres - - COMANAGE_REGISTRY_DATABASE=registry - - COMANAGE_REGISTRY_DATABASE_HOST=comanage-registry-database - - COMANAGE_REGISTRY_DATABASE_USER=registry_user - - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/comanage_registry_postgres_user_password - - COMANAGE_REGISTRY_EMAIL_FROM='account@gmail.com' - - COMANAGE_REGISTRY_EMAIL_TRANSPORT=Smtp - - COMANAGE_REGISTRY_EMAIL_HOST=tls://smtp.gmail.com - - COMANAGE_REGISTRY_EMAIL_PORT=465 - - COMANAGE_REGISTRY_EMAIL_ACCOUNT=account@gmail.com - - COMANAGE_REGISTRY_EMAIL_ACCOUNT_PASSWORD_FILE=/run/secrets/comanage_registry_email_account_password - - COMANAGE_REGISTRY_SECURITY_SALT_FILE=/run/secrets/comanage_registry_security_salt - - COMANAGE_REGISTRY_SECURITY_SEED_FILE=/run/secrets/comanage_registry_security_seed - - SHIBBOLETH_SP_ENTITY_ID=https://my.org/shibboleth - - SHIBBOLETH_SP_CERT=/run/secrets/shibboleth_sp_cert_file - - SHIBBOLETH_SP_PRIVKEY=/run/secrets/shibboleth_sp_privkey_file - - SHIBBOLETH_SP_SAMLDS_URL=https://my.org/registry/pages/eds/index - - SHIBBOLETH_SP_METADATA_PROVIDER_XML_FILE=/run/secrets/shibboleth_sp_metadata_provider_xml - - HTTPS_CERT_FILE=/run/secrets/https_cert_file - - HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file - - ports: - - "80:80" - - "443:443" diff --git a/comanage-registry-stack/README.md b/comanage-registry-stack/README.md deleted file mode 100644 index 90e93bc..0000000 --- a/comanage-registry-stack/README.md +++ /dev/null @@ -1,43 +0,0 @@ - - -# Docker Stack Deploy for COmanage Registry - -This is an example Docker compose file to deploy COmanage -Registry with mod_auth_openidc for Apache HTTP Server -for authentication and a MariaDB database using Docker stack deploy. - -See the individual image Dockerfile templates and README -files for details on how to prepare the volumes and the -necessary contents including the COmanage Registry -configuration. - -## Deploy - -``` -docker stack deploy --compose-file comanage-registry-mod-auth-openidc-mariadb-stack.yml comanage-registry -``` - -## Tear Down - -``` -docker stack rm comanage-registry -``` diff --git a/comanage-registry-stack/comanage-registry-mod-auth-openidc-mariadb-stack.yml b/comanage-registry-stack/comanage-registry-mod-auth-openidc-mariadb-stack.yml deleted file mode 100644 index 4696749..0000000 --- a/comanage-registry-stack/comanage-registry-mod-auth-openidc-mariadb-stack.yml +++ /dev/null @@ -1,104 +0,0 @@ -version: '3.1' - -services: - - comanage-registry-database: - image: mariadb - volumes: - - /opt/mariadb-data:/var/lib/mysql - environment: - - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/mysql_root_password - - MYSQL_DATABASE=registry - - MYSQL_USER=registry_user - - MYSQL_PASSWORD_FILE=/run/secrets/mysql_registry_user_password - secrets: - - mysql_root_password - - mysql_registry_user_password - networks: - - default - deploy: - replicas: 1 - - comanage-registry-ldap: - image: sphericalcowgroup/comanage-registry-slapd - volumes: - - /opt/slapd-data:/var/lib/ldap - - /opt/slapd-config:/etc/ldap/slapd.d - environment: - - SLAPD_CERT_FILE=/run/secrets/slapd_cert_file - - SLAPD_PRIVKEY_FILE=/run/secrets/slapd_privkey_file - - SLAPD_CHAIN_FILE=/run/secrets/slapd_chain_file - - OLC_ROOT_PW_FILE=/run/secrets/olc_root_pw - - OLC_SUFFIX=dc=my,dc=org - - OLC_ROOT_DN=cn=admin,dc=my,dc=org - secrets: - - slapd_cert_file - - slapd_privkey_file - - slapd_chain_file - - olc_root_pw - networks: - - default - ports: - - "636:636" - - "389:389" - deploy: - replicas: 1 - - comanage-registry: - image: sphericalcowgroup/comanage-registry:hotfix-2.0.x-mod-auth-openidc - volumes: - - /opt/comanage-registry-local:/local - environment: - - OIDC_CLIENT_ID_FILE=/run/secrets/oidc_client_id - - OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client_secret - - OIDC_PROVIDER_METADATA_URL_FILE=/run/secrets/oidc_provider_metadata_url - - OIDC_CRYPTO_PASSPHRASE_FILE=/run/secrets/oidc_crypto_passphrase - - REGISTRY_HOST_FILE=/run/secrets/registry_host - - HTTPS_CERT_FILE=/run/secrets/https_cert_file - - HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file - - COMANAGE_REGISTRY_ADMIN_GIVEN_NAME=ScottCmpAdmin - - COMANAGE_REGISTRY_ADMIN_FAMILY_NAME=Koranda - - COMANAGE_REGISTRY_ADMIN_USERNAME=http://cilogon.org/serverA/users/22981 - secrets: - - oidc_client_id - - oidc_client_secret - - oidc_provider_metadata_url - - oidc_crypto_passphrase - - registry_host - - https_cert_file - - https_privkey_file - networks: - - default - ports: - - "80:80" - - "443:443" - deploy: - replicas: 1 - -secrets: - mysql_root_password: - external: true - mysql_registry_user_password: - external: true - slapd_cert_file: - external: true - slapd_privkey_file: - external: true - slapd_chain_file: - external: true - olc_root_pw: - external: true - oidc_client_id: - external: true - oidc_client_secret: - external: true - oidc_provider_metadata_url: - external: true - oidc_crypto_passphrase: - external: true - registry_host: - external: true - https_cert_file: - external: true - https_privkey_file: - external: true diff --git a/docs/mod-auth-oidc-mariadb-stacks.md b/docs/mod-auth-oidc-mariadb-stacks.md new file mode 100644 index 0000000..a75bc08 --- /dev/null +++ b/docs/mod-auth-oidc-mariadb-stacks.md @@ -0,0 +1,278 @@ + + +# COmanage Registry Docker for Production with mod\_auth\_openidc and MariaDB using Docker stacks, swarm, and secrets + +Follow this recipe as an example production deployment of COmanage Registry +with mod\_auth\_openidc for authentication, a MariaDB database, and +an OpenLDAP slapd directory server. + +This recipe uses Docker service stacks, swarm, and secrets rather than docker-compose. + +## Recipe + +* Define `COMANAGE_REGISTRY_VERSION`. Currently we recommend + +``` +export COMANAGE_REGISTRY_VERSION=hotfix-2.0.x +``` + +* Build a local image for COmanage Registry if you have not already: + +``` +pushd comanage-registry-mod-auth-openidc +sed -e s/%%COMANAGE_REGISTRY_VERSION%%/${COMANAGE_REGISTRY_VERSION}/g Dockerfile.template > Dockerfile +docker build -t comanage-registry:${COMANAGE_REGISTRY_VERSION}-mod-auth-openidc . +popd +``` + +* It is not necessary to build a local image for the MariaDB container. The official MariaDB image +is sufficient. + +* Build a local image of OpenLDAP slapd for COmanage Registry if you have not already: + +``` +pushd comanage-registry-slapd +docker build -t comanage-registry-slapd . +popd +``` + +* Create directories to persist the relational database, COmanage Registry +local configuration, slapd configuration, slapd directory data: +``` +mkdir -p /docker/var/lib/mysql +mkdir -p /docker/srv/comanage-registry/local +mkdir -p /docker/var/lib/ldap +mkdir -p /docker/etc/ldap/slapd.d +``` + +* Create a single node swarm: +``` +docker swarm init +``` + +Store secrets and inject other deployment details using Docker secrets. +Be sure to create your own secrets and do not reuse the examples +below. + + +Create a root password for the MariaDB database: +``` +echo "4vdecnEHzwUNKA1FlvgE" | docker secret create mysql_root_password - +``` + +Create a password, used by MariaDB, for the COmanage Registry database user: + +``` +echo "34MF72AyBWgaTm3OLbc9" | \ + docker secret create mysql_registry_user_password - +``` + +Store that same password again to be used by the COmanage Registry container: + +``` +echo "202ZIBSipiP2cOhoTDFK" | \ + docker secret create comanage_registry_database_user_password - +``` + +Obtain the OIDC client secret and the mod\_auth\_openidc OIDC crypto +passphrase and store them as secrets: + +``` +echo "myproxy:oa4mp,2012:/client_id/630031683213792271192646355167031832" \ + | docker secret create oidc_client_id - + + +echo "g4bu5n0jTfHnwKvf2itz" | docker secret create oidc_crypto_passphrase - +``` + +Use the slappasswd tool (package `slapd` on Debian) to create a strong hash for a strong +password for the directory root DN: + +``` +slappasswd -c '$6$rounds=5000$%.86s' +``` + +Store the hash in a file: + +``` +echo '{CRYPT}$6$rounds=5000$kER6wkUF91t4.r79$7OLbtO0qF9K9tQlVJAxpWFem.0KmnyWn1/1K0sVSEQELRuj87sc7GtJT7HpWBr8JfZHlbsG9ifrqN6EmJchQ8/' \ + > /docker/run/secrets/olc_root_pw +``` + +Put the X.509 certificate, private key, and chain files in place for slapd: + +``` +docker secret create slapd_cert_file cert.pem +docker secret create slapd_privkey_file privkey.pem +docker secret create slapd_chain_file chain.pem +``` + +Put the X.509 certificate and private key files in place +for Apache HTTP Server for HTTPS. The certificate file should +include the server certificate and any intermediate CA signing +certificates sorted from leaf to root: + +``` +docker secret create https_cert_file fullchain.pem +docker secret create https_privkey_file privkey.pem +``` + +* Create a docker-compose.yml by adjusting the example below: + +``` +version: '3.1' + +services: + + comanage-registry-database: + image: mariadb + volumes: + - /srv/docker/var/lib/mysql:/var/lib/mysql + environment: + - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/mysql_root_password + - MYSQL_DATABASE=registry + - MYSQL_USER=registry_user + - MYSQL_PASSWORD_FILE=/run/secrets/mysql_registry_user_password + secrets: + - mysql_root_password + - mysql_registry_user_password + networks: + - default + deploy: + replicas: 1 + + comanage-registry-ldap: + image: comanage-registry-slapd + volumes: + - /srv/docker/var/lib/ldap:/var/lib/ldap + - /srv/docker/etc/ldap/slapd.d:/etc/ldap/slapd.d + environment: + - SLAPD_CERT_FILE=/run/secrets/slapd_cert_file + - SLAPD_PRIVKEY_FILE=/run/secrets/slapd_privkey_file + - SLAPD_CHAIN_FILE=/run/secrets/slapd_chain_file + - OLC_ROOT_PW_FILE=/run/secrets/olc_root_pw + - OLC_SUFFIX=dc=my,dc=org + - OLC_ROOT_DN=cn=admin,dc=my,dc=org + secrets: + - slapd_cert_file + - slapd_privkey_file + - slapd_chain_file + - olc_root_pw + networks: + - default + ports: + - "636:636" + - "389:389" + deploy: + replicas: 1 + + comanage-registry: + image: comanage-registry:hotfix-2.0.x + volumes: + - /srv/docker/srv/comanage-registry/local:/srv/comanage-registry/local + environment: + - OIDC_CLIENT_ID=myproxy:oa4mp,2012:/client_id/zC8kr2KG5wBxWIQ6YLu0 + - OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client_secret + - OIDC_PROVIDER_METADATA_URL=https://cilogon.org/.well-known/openid-configuration + - OIDC_CRYPTO_PASSPHRASE_FILE=/run/secrets/oidc_crypto_passphrase + - REGISTRY_HOST=registry.my.org + - HTTPS_CERT_FILE=/run/secrets/https_cert_file + - HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file + - COMANAGE_REGISTRY_ADMIN_USERNAME=http://cilogon.org/serverA/users/22981 + - COMANAGE_REGISTRY_DATASOURCE=Database/Mysql + - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/comanage_registry_database_user_password + - COMANAGE_REGISTRY_EMAIL_TRANSPORT=Smtp + - COMANAGE_REGISTRY_EMAIL_HOST=smtp.ncsa.uiuc.edu + - COMANAGE_REGISTRY_EMAIL_PORT=25 + secrets: + - comanage_registry_database_user_password + - oidc_client_secret + - oidc_crypto_passphrase + - https_cert_file + - https_privkey_file + networks: + - default + ports: + - "80:80" + - "443:443" + deploy: + replicas: 1 + +secrets: + comanage_registry_database_user_password: + external: true + mysql_root_password: + external: true + mysql_registry_user_password: + external: true + slapd_cert_file: + external: true + slapd_privkey_file: + external: true + slapd_chain_file: + external: true + olc_root_pw: + external: true + oidc_client_secret: + external: true + oidc_crypto_passphrase: + external: true + https_cert_file: + external: true + https_privkey_file: + external: true +``` + +Note especially the value for `COMANAGE_REGISTRY_ADMIN_USERNAME`. +This is the value that mod\_auth\_openidc expects to consume in the +ID token from the OP that authenticates the first platform administrator. +By default mod\_auth\_openidc will expect to consume that identifier +from the sub claim asserted for the admin by the OP. + +Bring up the services using docker stack deploy: + +``` +docker stack deploy --compose-file docker-compose.yml comanage-registry +``` + +COmanage Registry will be exposed on port 443 (HTTP). Use a web browser +to browse, for example, to + +``` +https://localhost/registry/ +``` + +If you have properly federated the OIDC client with the OP that the +first platform administrator will use you can click on "Login" and be +redirected to the OP for authentication. + +Production deployments need to send email, usually using an authenticated +account on a SMTP server. You may configure the details for your SMTP server +by editing the file `email.php` that the entrypoint script automatically +creates in `/docker/srv/comanage-registry/local/Config`. + +To stop the services and tear down the stack run + +``` +docker stack rm comanage-registry +``` + diff --git a/recipes/production-mod-auth-openidc-mariadb/README.md b/recipes/production-mod-auth-openidc-mariadb/README.md deleted file mode 100644 index 6c8adb0..0000000 --- a/recipes/production-mod-auth-openidc-mariadb/README.md +++ /dev/null @@ -1,146 +0,0 @@ - - -# COmanage Registry Docker for Production with mod_auth_openidc and MariaDB - -Follow this recipe as an example production deployment of COmanage Registry -with mod_auth_openidc for authentication, a MariaDB database, and -an OpenLDAP slapd directory server. - -This recipe uses a single node Docker swarm with secrets. - -## Recipe - -Begin by creating the swarm: - -``` -docker swarm init -``` - -Create an overlay network: - -``` -docker network create \ - --driver overlay \ - --subnet 10.0.9.0/24 \ - --opt encrypted \ - comanage-registry-internal-network -``` - -Store the secrets (be sure to create and store your own secrets): - -``` -echo "vvd8cnEHzwUAKA1FEvgE" | docker secret create mysql_root_password - - -echo "ePqoNOipDc3737n7XJfc" | docker secret create mysql_registry_user_password - - -echo "some_client_id" | docker secret create oidc_client_id - - -echo "some_client_secret" | docker secret create oidc_client_secret - - -echo "https://my.service.org/.well-known/openid-configuration" \ - | docker secret create oidc_provider_metadata_url - - -echo "hwL5OIVkEBr34Az2OrLC" | docker secret create oidc_crypto_passphrase - - -echo "registry.my.org" | docker secret create registry_host - - -docker secret create https_cert_file my.org.crt - -docker secret create https_privkey_file my.org.key - -docker secret create slapd_cert_file my.org.crt - -docker secret create slapd_privkey_file my.org.key - -docker secret create slapd_chain_file chain.pem -``` - -Choose a password for the slapd root DN and use the -`slappasswd` command line tool to generate a hash of the password: - -``` -slappasswd -c '$6$rounds=5000$%.86s' -``` - -Store the hash as a secret: - -``` -echo '{CRYPT}$6$rounds=5000$PvNNFYcGZgiswGxp$mGU2iXuKGkDBRpv4VU1ZTli/S9MZy8DQzj66zpLuHnNQFJ5/ADv3Ij3jsKeGhJq3kFn8yv9RMhEDb/CFoCXxf1' | docker secret create olc_root_pw - -``` - -Create directories on the Docker host to persist data: - -``` -mkdir -p /opt/mariadb-data -mkdir -p /opt/slapd-data -mkdir -p /opt/slapd-config -mkdir -p /opt/comanage-registry-local/Config -``` - -Create the files `database.php` and `email.php` in `/opt/comanage-registry-loca/Config`: - -``` -# cat database.php - 'Database/Mysql', - 'persistent' => false, - 'host' => 'comanage-registry-database', - 'login' => 'registry_user', - 'password' => 'password', - 'database' => 'registry', - 'prefix' => 'cm_', - ); - -} - -# cat email.php - 'Smtp', - 'from' => array('help@my.org' => 'My Org'), - 'host' => 'smtp.my.org', - 'port' => 25, - 'timeout' => 30 - ); -} - -``` - -Deploy the COmanage Registry stack: - -``` -docker stack deploy --compose-file comanage-registry-mod-auth-openidc-mariadb-stack.yml \ - comanage-registry -``` - -To deprovision the stack: - -``` -docker stack rm comanage-registry -```