diff --git a/README.md b/README.md index 17a616a..d77584c 100644 --- a/README.md +++ b/README.md @@ -22,30 +22,114 @@ limitations under the License. # COmanage Registry Docker ## What it is -Dockerfile templates and associated files to -build images for -[COmanage Registry](https://spaces.internet2.edu/display/COmanage/Home), as well as -documentation and recipes for both simple deployments to use for evaluating -COmanage Registry and deployments ready for production. - -## What is here - -* [Dockerfile templates](#Dockerfile-templates) -* Recipes - * [Simple deployment for evaluation, no persistence](recipes/simple-no-persistence/README.md) - * [Simple deployment for evaluation with persistence](recipes/simple-with-persistence/README.md) - * [Production deployment using Docker stacks with mod_auth_openidc and MariaDB](recipes/production-mod-auth-openidc-mariadb/README.md) - * [Production deployment using docker-compose with Shibboleth SP and PostgreSQL](recipes/production-shibboleth-sp-postgres/README.md) - - -## Dockerfile templates - -* [COmanage Registry](comanage-registry/README.md) (no authentication, primarily for developers) -* [COmanage Registry with Basic Authentication](comanage-registry-basic-auth/README.md) -* [COmanage Registry with Shibboleth](comanage-registry-shibboleth-sp/README.md) Native SP for Apache Authentication -* [Example PostgreSQL](comanage-registry-postgres/README.md) image for use with COmanage Registry -* [Example MariaDB](comanage-registry-mariadb/README.md) image for use with COmanage Registry -* [Example OpenLDAP slapd](comanage-registry-slapd/README.md) image for use with COmanage Registry -* [Example Docker stack compose file](comanage-registry-stack/README.md) -* [Example docker-compose file](comanage-registry-compose/README.md) +Docker version of [COmanage +Registry](https://spaces.internet2.edu/display/COmanage/Home). + +COmanage Registry is a web application that requires a relational database +and an authentication mechanism such as +[Shibboleth](http://shibboleth.net/products/service-provider.html), +[SimpleSAMLphp](https://simplesamlphp.org/), +[mod_auth_openidc](https://github.com/pingidentity/mod_auth_openidc), +or just simple [Basic Authentication](https://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html). +Since COmanage Registry itself is agnostic about the database and authentication +mechanism used this repository includes multiple Dockerfiles to build images that use various +combinations of tools. + +## How To + +* Install Docker. These instructions require version 17.03.1 or higher. + +* Install [Docker Compose](https://docs.docker.com/compose/). These instructions require +version 1.13.0 or higher. + +* Clone this repository: + +``` +git clone https://github.com/Internet2/comanage-registry-docker.git +cd comanage-registry-docker +``` + +* Define `COMANAGE_REGISTRY_VERSION`. Currently we recommend + +``` +export COMANAGE_REGISTRY_VERSION=hotfix-2.0.x +``` + +* Build a local image for COmanage Registry: + +``` +pushd comanage-registry-basic-auth +sed -e s/%%COMANAGE_REGISTRY_VERSION%%/${COMANAGE_REGISTRY_VERSION}/g Dockerfile.template > Dockerfile +docker build -t comanage-registry:${COMANAGE_REGISTRY_VERSION}-basic-auth . +popd +``` + +* Build a local image of PostgreSQL for COmanage Registry: +``` +pushd comanage-registry-postgres +docker build -t comanage-registry-postgres . +popd +``` +* Create a docker-compose.yml file: +``` +version: '3.1' + +services: + + comanage-registry-database: + image: comanage-registry-postgres + + comanage-registry: + image: comanage-registry:hotfix-2.0.x-basic-auth + ports: + - "80:80" + - "443:443" +``` + +* Start the services: +``` +docker-compose up -d +``` + +* Browse to port 443 on the host, for example `https://localhost/`. You will have to + click through the warning from your browser about the self-signed certificate used + for HTTPS. + +* Click `Login` and when prompted enter `registry.admin` as the username and `password` +for the password. + +* Visit the [COmanage wiki](https://spaces.internet2.edu/display/COmanage/Setting+Up+Your+First+CO) +to learn how to create your first collaborative organization (CO) and begin using +the platform. + +* To stop the services: +``` +docker-compose stop +``` + +* To remove the containers and networks: +``` +docker-compose down +``` + +### Important Notes +The instructions above are *not suitable for a production deployment* for two reasons: + +1. The deployed services use default and easily guessed passwords. +2. No data is persisted. When the containers are destoryed so is your data. + +## Next Steps +To evolve your COmanage Registry deployment examine the documentation +in the [docs directory](docs/README.md) or follow these direct links: + +* [Persist data using host-mounted volumes](docs/basic-auth-postgres-persist.md) +* [Use MariaDB instead of PostgreSQL](docs/basic-auth-mariadb-persist.md) +* [Add OpenLDAP slapd for provisioning](docs/openldap-slapd.md) +* [Advanced configuration](docs/advanced-configuration.md) +* [Complete example recipe for production deployment](docs/shibboleth-sp-postgres-compose.md) +* [Using Docker service stacks and Docker secrets](docs/stacks-secrets.md) + + + + diff --git a/docs/advanced-configuration.md b/docs/advanced-configuration.md new file mode 100644 index 0000000..c2701ba --- /dev/null +++ b/docs/advanced-configuration.md @@ -0,0 +1,270 @@ + + +# COmanage Registry Docker +## Advanced Configuration Options + +The services deployed in containers instantiated using images built from this repository may be +configured in a number of different ways. + +##### Table of Contents +[Environment Variables](#environ) +[Secrets](#secrets) + +## Environment Variables + +Most deployment details may be set using environment variables set for the container. +The entrypoint scripts will attempt to use values from environment variables and if not +present reasonable defaults will be used. *Note that some defaults like passwords are +easily guessable and not suitable for production deployments*. + +The complete list of environment variables available for configuration is listed in +the documentation for each image. See each image directory in this repository for +details. + +Below are some examples of common environment variables deployers choose to set for each +component. + +### COmanage Registry + +| Environment Variable | Description | Default | Example 1 | Example 2 | +| -------------------- | ----------- | --------- | --------- | ------- | +| COMANAGE_REGISTRY_DATASOURCE | database type | Database/Postgres | Database/Postgres | Database/Mysql | +| COMANAGE_REGISTRY_DATABASE_USER| database user | registry_user | comanage | comanage_user | +| COMANAGE_REGISTRY_DATABASE_USER_PASSWORD | database user password | password | AFH9OiyuowiY3Wq6qX0j | qVcsJPo7$@ | +| COMANAGE_REGISTRY_EMAIL_HOST | SMTP email host | tls://smtp.gmail.com | tls://some.server.edu | some.server.edu | +| COMANAGE_REGISTRY_EMAIL_PORT | SMTP email port | 465 | 465 | 25 | +| COMANAGE_REGISTRY_EMAIL_FROM | From: address | account@gmail.com | registry@some.org | comanage@school.edu | +| COMANAGE_REGISTRY_EMAIL_ACCOUNT | SMTP email account | account@gmail.com | service_account | some_user | +| COMANAGE_REGISTRY_EMAIL_ACCOUNT_PASSWORD | SMTP email account password | password | jI%ASJ!1U | airwu883Y | + +### PostgreSQL + +| Environment Variable | Description | Default | Example 1 | Example 2 | +| -------------------- | ----------- | --------- | --------- | ------- | +| POSTGRES_PASSWORD | database admin password | none | $cu9@2!qp&3R | 4vGb10sI#AI | +| COMANAGE_REGISTRY_POSTGRES_USER | registry database user | registry_user | comanage | comanage_user | +| COMANAGE_REGISTRY_POSTGRES_USER_PASSWORD | registry database user password | password | AFH9OiyuowiY3Wq6qX0j | qVcsJPo7$@ | + +### MariaDB + +| Environment Variable | Description | Default | Example 1 | Example 2 | +| -------------------- | ----------- | --------- | --------- | ------- | +| MYSQL_ROOT_PASSWORD | database admin password | none | JaMKH5xAB64E9 | 6XET#82NFm& | +| MYSQL_USER | registry database user | registry_user | comanage | comanage_user | +| MYSQL_PASSWORD | registry database user password | none | 9vmKxJGwD!iU | o8rhqq4Sr%R | + +### Shibboleth SP +Coming soon... + +### mod_auth_oidc +Coming soon... + +### OpenLDAP slapd +Coming soon... + +## Secrets + +Some deployers prefer not to use environment variables to inject secrets to avoid having +secrets in YAML files saved for example in a code repository. + +An alternative is to put the secret in a file mounted into the container and point +to the file location using an environment variable. For example if the file + +``` +/run/secrets/comanage_registry_postgres_user_password +``` + +is mounted in the container and holds the password and the container environment contains + +``` +COMANAGE_REGISTRY_POSTGRES_USER_PASSWORD_FILE=/run/secrets/comanage_registry_postgres_user_password +``` + +then the entrypoint script will set the password to the value read from the file. + +Here is an example compose file that uses secrets read from files mounted in +the containers: + +``` +version: '3.1' + +services: + + comanage-registry-database: + image: mariadb + volumes: + - /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_password + + comanage-registry: + image: comanage-registry:hotfix-2.0.x-basic-auth + environment: + - COMANAGE_REGISTRY_DATASOURCE=Database/Mysql + - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/mysql_password + ports: + - "80:80" + - "443:443" +``` + +*All configuration details that may be set using an environment variable can also be set +using a file and environment variable of the same name appended with `_FILE`*. + +*When present an environment variable pointing to a file inside the container overrides +an otherwise configured environment variable*. + +## X.509 Certificates and Private Keys + +### COmanage Registry + +The certificate, private key, and CA signing file or chain file used for HTTPS may +be injected into the COmanage Registry container using environment variables +to point to files mounted into the container. + +For example: + +``` +version: '3.1' + +services: + + comanage-registry-database: + image: mariadb + volumes: + - /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_password + + comanage-registry: + image: comanage-registry:hotfix-2.0.x-basic-auth + environment: + - COMANAGE_REGISTRY_DATASOURCE=Database/Mysql + - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/mysql_password + - HTTPS_CERT_FILE=/run/secrets/https_cert_file + - HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file + - HTTPS_CHAIN_FILE=/run/secrets/https_chain_file + ports: + - "80:80" + - "443:443" +``` + +Alternatively you can directly mount files in the container to + +``` +/etc/apache2/cert.pem +/etc/apache2/privkey.pem +/etc/apache2/chain.pem +``` + +If no files are configured the containers use "snakeoil" self-signed certificates +for HTTPS by default. + +### Shibboleth SP + +The SAML certificate and private key used for decryption (and sometimes signing) +by the Shibboleth SP may be injected into the COmanage Registry container using +environment variables to point to files mounted into the container. + +For example: + +``` +version: '3.1' + +services: + + comanage-registry-database: + image: mariadb + volumes: + - /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_password + + comanage-registry: + image: comanage-registry:hotfix-2.0.x-basic-auth + environment: + - COMANAGE_REGISTRY_DATASOURCE=Database/Mysql + - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD_FILE=/run/secrets/mysql_password + - HTTPS_CERT_FILE=/run/secrets/https_cert_file + - HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file + - HTTPS_CHAIN_FILE=/run/secrets/https_chain_file + - SHIBBOLETH_SP_CERT=/run/secrets/shibboleth_sp_cert + - SHIBBOLETH_SP_PRIVKEY=/run/secrets/shibboleth_sp_privkey + ports: + - "80:80" + - "443:443" +``` + +Alternatively you can directly mount files in the container to + +``` +/etc/shibboleth/sp-cert.pem +/etc/shibboleth/sp-key.pem +``` + +If no files are configured the container uses a default self-signed certificate +*this is the same for all images and not suitable for production*. + +### OpenLDAP slapd + +Coming soon... + +## Full control + +Deployers needing full control may inject configuration and deployment details directly. +The entrypoint scripts will *not* overwrite any details found so directly injected +details always override environment variables. + +### COmanage Registry + +COmanage Registry expects to find all local configuration details +in the container at `/srv/comanage-registry/local`. A deployer may therefore mount +a directory at that location to provide any and all configuration details. Note, however, +that Registry expects to find a particular directory structure under +`/srv/comanage-registry/local` and will not function properly if the structure is not +found. The entrypoint script will create the necessary structure if it does not find it +so it is recommended to mount an empty directory for the first deployment, let the +entrypoint script create the structure, then later adjust the details as necessary +for your deployment. + +### Shibboleth SP + +All Shibboleth SP configuration is available inside the container in +`/etc/shibboleth`. A deployer may therefore mount into that directory any +necessary adjustment to the Shibboleth configuration, such as static metadata +files, metadata signing certificates, or advanced attribute filtering +configurations. + +A default set of all configuration files is available in the image. + +### OpenLDAP slapd + +Coming soon... + diff --git a/docs/basic-auth-mariadb-persist.md b/docs/basic-auth-mariadb-persist.md new file mode 100644 index 0000000..8ff04ed --- /dev/null +++ b/docs/basic-auth-mariadb-persist.md @@ -0,0 +1,113 @@ + + +# COmanage Registry Docker +## With Basic Authentication, MariaDB, and persisted data + +* 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-basic-auth +sed -e s/%%COMANAGE_REGISTRY_VERSION%%/${COMANAGE_REGISTRY_VERSION}/g Dockerfile.template > Dockerfile +docker build -t comanage-registry:${COMANAGE_REGISTRY_VERSION}-basic-auth . +popd +``` + +* It is not necessary to build a local image of MariaDB for COmanage Registry. You can +use the [official MariaDB image from Docker Hub](https://hub.docker.com/_/mariadb/). + + +* Create a directory to persist data in the relational database: +``` +mkdir -p /docker/var/lib/mysql +mkdir -p /docker/srv/comanage-registry/local +``` + +* Create a docker-compose.yml file. Be sure to replace the password examples +below with your own choices. +``` +version: '3.1' + +services: + + comanage-registry-database: + image: mariadb + volumes: + - /docker/var/lib/mysql:/var/lib/mysql + environment: + - MYSQL_ROOT_PASSWORD=tkrT3MI4H2otxGMuxqoE + - MYSQL_DATABASE=registry + - MYSQL_USER=registry_user + - MYSQL_PASSWORD=vy4O6XF58gl1fMpf6rRg + + comanage-registry: + image: comanage-registry:hotfix-2.0.x-basic-auth + volumes: + - /docker/srv/comanage-registry/local:/srv/comanage-registry/local + environment: + - COMANAGE_REGISTRY_DATASOURCE=Database/Mysql + # Password below must be same as for MYSQL_PASSWORD above + - COMANAGE_REGISTRY_DATABASE_USER_PASSWORD=vy4O6XF58gl1fMpf6rRg + ports: + - "80:80" + - "443:443" +``` + +* Start the services: +``` +docker-compose up -d +``` + +* Browse to port 443 on the host, for example `https://localhost/` + +* Click `Login` and when prompted enter `registry.admin` as the username and `password` +for the password. + +* Visit the [COmanage wiki](https://spaces.internet2.edu/display/COmanage/Setting+Up+Your+First+CO) +to learn how to create your first collaborative organization (CO) and begin using +the platform. + +* To stop the services: +``` +docker-compose stop +``` + +* To remove the containers and networks: +``` +docker-compose down +``` + +Even though the containers have been removed the data is persisted. You may +bring up the services again and resume where you left off. + +### Important Notes +The instructions above are *not suitable for a production deployment* +because the deployed services use default and easily guessed passwords. + + + + diff --git a/docs/basic-auth-postgres-persist.md b/docs/basic-auth-postgres-persist.md new file mode 100644 index 0000000..6839e9a --- /dev/null +++ b/docs/basic-auth-postgres-persist.md @@ -0,0 +1,108 @@ + + +# COmanage Registry Docker +## With Basic Authentication, PostgreSQL, and persisted data + +* 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-basic-auth +sed -e s/%%COMANAGE_REGISTRY_VERSION%%/${COMANAGE_REGISTRY_VERSION}/g Dockerfile.template > Dockerfile +docker build -t comanage-registry:${COMANAGE_REGISTRY_VERSION}-basic-auth . +popd +``` + +* Build a local image of PostgreSQL for COmanage Registry if you have not already: +``` +pushd comanage-registry-postgres +docker build -t comanage-registry-postgres . +popd +``` + +* Create directories to persist the relational database and COmanage Registry +local configuration: +``` +mkdir -p /docker/var/lib/postgresql/data +mkdir -p /docker/srv/comanage-registry/local +``` + +* Create a docker-compose.yml file that mounts the directories you created +as volumes in the database container: +``` +version: '3.1' + +services: + + comanage-registry-database: + image: comanage-registry-postgres + volumes: + - /docker/var/lib/postgresql/data:/var/lib/postgresql/data + + comanage-registry: + image: comanage-registry:hotfix-2.0.x-basic-auth + volumes: + - /docker/srv/comanage-registry/local:/srv/comanage-registry/local + ports: + - "80:80" + - "443:443" +``` + +* Start the services: +``` +docker-compose up -d +``` + +* Browse to port 443 on the host, for example `https://localhost/` + +* Click `Login` and when prompted enter `registry.admin` as the username and `password` +for the password. + +* Visit the [COmanage wiki](https://spaces.internet2.edu/display/COmanage/Setting+Up+Your+First+CO) +to learn how to create your first collaborative organization (CO) and begin using +the platform. + +* To stop the services: +``` +docker-compose stop +``` + +* To remove the containers and networks: +``` +docker-compose down +``` + +Even though the containers have been removed the data is persisted. You may +bring up the services again and resume where you left off. + +### Important Notes +The instructions above are *not suitable for a production deployment* +because the deployed services use default and easily guessed passwords. + + + + diff --git a/docs/shibboleth-sp-postgres-compose.md b/docs/shibboleth-sp-postgres-compose.md new file mode 100644 index 0000000..16acf5d --- /dev/null +++ b/docs/shibboleth-sp-postgres-compose.md @@ -0,0 +1,243 @@ + + +# COmanage Registry Docker for Production with Shibboleth SP and PostgreSQL using docker-compose + +Follow this recipe as an example production deployment of COmanage Registry +with the Shibboleth SP for authentication, a PostgreSQL database, and +an OpenLDAP slapd directory server. + +This recipe uses docker-compose rather than Docker service stacks. Version +1.13.0 or higher of docker-compose is required: + +``` +$ docker-compose --version +docker-compose version 1.13.0, build 1719ceb +``` + +## 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 (building the + Shibboleth SP from source takes time): + +``` +pushd comanage-registry-shibboleth-sp +sed -e s/%%COMANAGE_REGISTRY_VERSION%%/${COMANAGE_REGISTRY_VERSION}/g Dockerfile.template > Dockerfile +docker build -t comanage-registry:${COMANAGE_REGISTRY_VERSION}-shibboleth-sp . +popd +``` + +* Build a local image of PostgreSQL for COmanage Registry if you have not already: + +``` +pushd comanage-registry-postgres +docker build -t comanage-registry-postgres . +popd +``` + +* 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, and to +hold secrets and other injected details: +``` +mkdir -p /docker/var/lib/postgresql/data +mkdir -p /docker/srv/comanage-registry/local +mkdir -p /docker/var/lib/ldap +mkdir -p /docker/etc/ldap/slapd.d +mkdir -p /docker/run/secrets +``` + +Below we create and store secrets in files using simple commands but you +could use any configuration management or deployment orchestration tool +you like such as Puppet, Chef, Ansible, Salt, or whichever tool is your +favorite. Be sure to create your own secrets and do not reuse the examples +below. + +Create a file with the password for the postgres user (that is, the +equivalent of a "root" password for the database): + +``` +echo 'xyt8Op3BCwdI5ETcVfQM' \ + > /docker/run/secrets/postgres_password +``` + +Create a file with the password for the COmanage Registry database user: + +``` +echo 'DqiMMWjzVOotAHX8WL9J' \ + > /docker/run/secrets/comanage_registry_postgres_user_password +``` + +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: + +``` +cp cert.pem /docker/run/secrets/slapd_cert_file +cp privkey.pem /docker/run/secrets/slapd_privkey_file +cp chain.pem /docker/run/secrets/slapd_chain_file +``` + +Put the X.509 certificate, private key, and chain files in place +for Apache HTTP Server for HTTPS (it is likely these are the same as +for slapd): + +``` +cp cert.pem /docker/run/secrets/https_cert_file +cp privkey.pem /docker/run/secrets/https_privkey_file +cp chain.pem /docker/run/secrets/https_chain_file +``` + +Put the Shibboleth SP SAML certificate and key files in place: + +``` +cp sp-cert.pem /docker/run/secrets/shibboleth_sp_cert_file +cp sp-key.pem /docker/run/secrets/shibboleth_sp_privkey_file +``` + +Create a file with the Shibboleth SP metadata configuration. This example +creates an XML comment which allows the Shibboleth daemon shibd to start, +but for a production scenario you will want to create a file with any +valid `` configuration. See the Shibboleth SP documentation +for details. + +``` +echo '' \ + > /docker/run/secrets/shibboleth_sp_metadata_provider_xml +``` + +* Create a docker-compose.yml by adjusting the example below: + +``` +version: '3.1' + +services: + + comanage-registry-database: + image: comanage-registry-postgres + volumes: + - /docker/var/lib/postgresql/data:/var/lib/postgresql/data + - /docker/run/secrets:/run/secrets + environment: + - POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password + - COMANAGE_REGISTRY_POSTGRES_USER_PASSWORD_FILE=/run/secrets/comanage_registry_postgres_user_password + + comanage-registry-ldap: + image: comanage-registry-slapd + volumes: + - /docker/var/lib/ldap:/var/lib/ldap + - /docker/etc/ldap/slapd.d:/etc/ldap/slapd.d + - /docker/run/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: + - /docker/srv/comanage-registry/local:/srv/comanage-registry/local + - /docker/run/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_DATABASE_USER_PASSWORD_FILE=/run/secrets/comanage_registry_postgres_user_password + - 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 + - HTTPS_CHAIN_FILE=/run/secrets/https_chain_file + + ports: + - "80:80" + - "443:443" +``` + +Note especially the value for `COMANAGE_REGISTRY_ADMIN_USERNAME`. +This is the value that the Shibboleth SP expects to consume in a SAML +assertion from the IdP that authenticates the first platform administrator. +By default the Shibboleth SP will expect to consume that identifier +from the eduPersonPrincipalName attribute asserted for the admin by the IdP. + +Bring up the services using docker-compose: + +``` +docker-compose up -d +``` + +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 Shibboleth SP with the IdP that the +first platform administrator will use you can click on "Login" and be +redirected to the IdP for authentication. + +To stop the services run + +``` +docker-compose stop +``` + +To remove the containers run + +``` +docker-compose down +``` + diff --git a/recipes/production-shibboleth-sp-postgres/README.md b/recipes/production-shibboleth-sp-postgres/README.md deleted file mode 100644 index f08572c..0000000 --- a/recipes/production-shibboleth-sp-postgres/README.md +++ /dev/null @@ -1,210 +0,0 @@ - - -# COmanage Registry Docker for Production with Shibboleth SP and PostgreSQL using docker-compose - -Follow this recipe as an example production deployment of COmanage Registry -with the Shibboleth SP for authentication, a PostgreSQL database, and -an OpenLDAP slapd directory server. - -This recipe uses docker-compose rather than docker stacks. Version -1.13.0 or higher of docker-compose is required: - -``` -$ docker-compose --version -docker-compose version 1.13.0, build 1719ceb -``` - -## Recipe - -Define `COMANAGE_REGISTRY_VERSION` for the version you wish to deploy. -The current recommendation for deploying with Docker is - -``` -export COMANAGE_REGISTRY_VERSION=hotfix-2.0.x -``` - -Build images for COmanage Registry with Shibboleth SP, OpenLDAP, -and PostgreSQL for COmanage Registry using the Dockerfile templates -and instructions for the individual components: - -* [COmanageRegistry with Shibboleth SP](../../comanage-registry-shibboleth-sp/README.md) -* [PostgreSQL for COmanage Regsitry](../../comanage-registry-postgres/README.md) -* [OpenLDAP slapd for COmanage Registry](../../comanage-registry-slapd/README.md) - -Copy the [docker-compose yaml file](../../comanage-registry-compose/comanage-registry-shibboleth-sp-postgres-compose.yml) -for COmanage Registry with Shibboleth SP and PostgreSQL: - -``` -cp comanage-registry-shibboleth-sp-postgres-compose.yml docker-compose.yml -``` - -Examine `docker-compose.yml` and adjust configuration details as necessary -for your deployment. See the documentation for the individual components for -details on which configuration details may be injected using environment -variables and files. - -Note especially the value for `COMANAGE_REGISTRY_ADMIN_USERNAME`. -This is the value that the Shibboleth SP expects to consume in a SAML -assertion from the IdP that authenticates the first platform administrator. -By default the Shibboleth SP will expect to consume that identifier -from the eduPersonPrincipalName attribute asserted for the admin by the IdP. - -The instructions that follow assume you are using the locations -of files and directories shown in the example docker-compose file. - -Create directories to hold secrets and other deployment -details, PostgresSQL data, slapd directory data, -and slapd configuration data: - - -``` -mkdir -p /opt/comanage-registry-deployment/secrets -mkdir -p /opt/comanage-registry-deployment/postgres-data -mkdir -p /opt/comanage-registry-deployment/slapd-data -mkdir -p /opt/comanage-registry-deployment/slapd-config -``` - -Below we create and store secrets in files using simple commands but you -could use any configuration management or deployment orchestration tool -you like such as Puppet, Chef, Ansible, Salt, or whichever tool is your -favorite. Be sure to create your own secrets and do not reuse the examples -below. - -Create a file with the password for the postgres user (that is, the -equivalent of a "root" password for the database): - -``` -echo 'xyt8Op3BCwdI5ETcVfQM' \ - > /opt/comanage-registry-deployment/secrets/postgres_password -``` - -Create a file with the password for the COmanage Registry database user: - -``` -echo 'DqiMMWjzVOotAHX8WL9J' \ - > /opt/comanage-registry-deployment/secrets/comanage_registry_postgres_user_password -``` - -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/' \ - > /opt/comanage-registry-deployment/secrets/olc_root_pw -``` - -Create a file with the password for the SMTP account that COmanage Registry -uses to send email: - -``` -echo '6CDYjyuEWPRiC5MwCnRp' \ - > /opt/comanage-registry-deployment/secrets/comanage_registry_email_account_password -``` - -Create a file with salt that COmanage Registry uses for some hashing -operations: - -``` -echo 'PdidP9nbU71rBzfasiM6lCVVEkHGZx4wOtAT6s6u' \ - > /opt/comanage-registry-deployment/secrets/comanage_registry_security_salt -``` - -Create a file with a security seed that COmanage Registry uses (must be all digits): - -``` -echo '44558711202925048514618319254' - > /opt/comanage-registry-deployment/secrets/comanage_registry_security_seed -``` - -Put the X.509 certificate, private key, and chain files in place for slapd: - -``` -cp cert.pem /opt/comanage-registry-deployment/secrets/slapd_cert_file -cp privkey.pem /opt/comanage-registry-deployment/secrets/slapd_privkey_file -cp chain.pem /opt/comanage-registry-deployment/secrets/slapd_chain_file -``` - -Put the X.509 certificate, private key, and chain files in place -for Apache HTTP Server for HTTPS (it is likely these are the same as -for slapd): - -``` -cp cert.pem /opt/comanage-registry-deployment/secrets/https_cert_file -cp privkey.pem /opt/comanage-registry-deployment/secrets/https_privkey_file -cp chain.pem /opt/comanage-registry-deployment/secrets/https_chain_file -``` - -Put the Shibboleth SP SAML certificate and key files in place: - -``` -cp sp-cert.pem /opt/comanage-registry-deployment/secrets/shibboleth_sp_cert_file -cp sp-key.pem /opt/comanage-registry-deployment/secrets/shibboleth_sp_privkey_file -``` - -Create a file with the Shibboleth SP metadata configuration. This example -creates an XML comment which allows the Shibboleth daemon shibd to start, -but for a production scenario you will want to create a file with any -valid `` configuration. See the Shibboleth SP documentation -for details. - -``` -echo '' \ - > /opt/comanage-registry-deployment/secrets/shibboleth_sp_metadata_provider_xml -``` - -Bring up the services using docker-compose: - -``` -docker-compose up -d -``` - -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 Shibboleth SP with the IdP that the -first platform administrator will use you can click on "Login" and be -redirected to the IdP for authentication. - -To stop the services run - -``` -docker-compose stop -``` - -To remove the containers (leaving the PostgreSQL and OpenLDAP slapd directory -data) run - -``` -docker-compose down -``` - -