From 78462758b83b54343a99c3860a2d5d23396f8977 Mon Sep 17 00:00:00 2001 From: Amro Misbah Date: Mon, 28 Nov 2022 08:30:12 +0200 Subject: [PATCH] docs: docker installation (#3027) * docs: docker installation * docs: add quick-start page * docs: readme.md and compose,md made identical * docs: adjust warning as per github pages syntex * docs: replace docker with docker compose * docs: github page identical to compose page * docs: remove yml file deletion * docs: fix * docs: fix helm chart url --- docker-jans-monolith/README.md | 65 +++++++------ docs/admin/install/docker-install/compose.md | 95 +++++++++++++++++++ .../quick-start.md} | 21 ++-- mkdocs.yml | 7 +- 4 files changed, 147 insertions(+), 41 deletions(-) create mode 100644 docs/admin/install/docker-install/compose.md rename docs/admin/install/{vm-install/quick-start-install.md => docker-install/quick-start.md} (77%) diff --git a/docker-jans-monolith/README.md b/docker-jans-monolith/README.md index baf78d7f7d8..33205c2f127 100644 --- a/docker-jans-monolith/README.md +++ b/docker-jans-monolith/README.md @@ -1,17 +1,27 @@ -# Overview +--- +tags: +- administration +- installation +- quick-start +- docker compose +--- -**This image is for testing and development purposes only! Use Janssen [helm charts](../charts) for production setups** +> **Warning** +> This image is for testing and development purposes only. Use Janssen [helm charts](https://github.com/JanssenProject/jans/tree/main/charts/janssen) for production setups. -Docker monolith image packaging for Janssen.This image packs janssen services including, the auth-server, config-api, fido2, and scim. +## Overview -## Versions +Docker monolith image packaging for Janssen. This image packs janssen services including the auth-server, config-api, fido2, and scim. + +## Pre-requisites + +- [Docker](https://docs.docker.com/install) +- [Docker compose](https://docs.docker.com/compose/install/) -See [Releases](https://github.com/JanssenProject/docker-jans-monolith/releases) for stable versions. This image should never be used in production. -For bleeding-edge/unstable version, use `janssenproject/monolith:1.0.4_dev`. ## Environment Variables -The following environment variables are supported by the container: +Installation depends on the set of environment variables shown below. These environment variables can be set to customize installation as per the need. If not set, the installer uses default values. | ENV | Description | Default | |-------------------------|--------------------------------------------------|--------------------------------------------------| @@ -32,35 +42,37 @@ The following environment variables are supported by the container: | `MYSQL_HOST` | MySQL host. | `mysql` which is the docker compose service name | -## Pre-requisites +## How to run -- [Docker](https://docs.docker.com/install). Docker compose should be installed by default with Docker. +Download the compose file -## How to run +```bash + +wget https://raw.githubusercontent.com/JanssenProject/jans/main/docker-jans-monolith/jans-mysql-compose.yml +``` + +This docker compose file runs two containers, the janssen monolith container and mysql container. ```bash docker compose -f jans-mysql-compose.yml up -d ``` -## Clean up +To view the containers running -Remove setup and volumes +```bash -``` -docker compose -f jans-mysql-compose.yml down && rm -rf jans-* +docker compose -f jans-mysql-compose.yml ps ``` -## Test +## Configure Janssen Server ```bash -docker exec -ti docker-jans-monolith-jans-1 bash -``` -Run -```bash -/opt/jans/jans-cli/config-cli.py -#or -/opt/jans/jans-cli/scim-cli.py +docker compose -f jans-mysql-compose.yml exec jans sh #This opens a bash terminal in the running container + +/opt/jans/jans-cli/config-cli.py #configure using the config-cli + +/opt/jans/jans-cli/scim-cli.py #configure using the scim-cli ``` ## Access endpoints externally @@ -74,11 +86,10 @@ Add to your `/etc/hosts` file the ip domain record which should be the ip of the After adding the record you can hit endpoints such as https://demoexample.jans.io/.well-known/openid-configuration -## Quick start +## Clean up -Grab a fresh ubuntu 22.04 lts VM and run: +Remove setup and volumes -```bash -wget https://raw.githubusercontent.com/JanssenProject/jans/main/automation/startjanssenmonolithdemo.sh && chmod u+x startjanssenmonolithdemo.sh && sudo bash startjanssenmonolithdemo.sh demoexample.jans.io MYSQL ``` - +docker compose -f jans-mysql-compose.yml down +``` diff --git a/docs/admin/install/docker-install/compose.md b/docs/admin/install/docker-install/compose.md new file mode 100644 index 00000000000..5e421beec66 --- /dev/null +++ b/docs/admin/install/docker-install/compose.md @@ -0,0 +1,95 @@ +--- +tags: +- administration +- installation +- quick-start +- docker compose +--- + +!!! Warning + **This image is for testing and development purposes only. Use Janssen [helm charts](https://github.com/JanssenProject/jans/tree/main/charts/janssen) for production setups.** + +## Overview + +Docker monolith image packaging for Janssen. This image packs janssen services including the auth-server, config-api, fido2, and scim. + +## Pre-requisites + +- [Docker](https://docs.docker.com/install) +- [Docker compose](https://docs.docker.com/compose/install/) + + +## Environment Variables + +Installation depends on the set of environment variables shown below. These environment variables can be set to customize installation as per the need. If not set, the installer uses default values. + +| ENV | Description | Default | +|-------------------------|--------------------------------------------------|--------------------------------------------------| +| `CN_HOSTNAME` | Hostname to install janssen with. | `demoexample.jans.io` | +| `CN_ADMIN_PASS` | Password of the admin user. | `1t5Fin3#security` | +| `CN_ORG_NAME` | Organization name. Used for ssl cert generation. | `Janssen` | +| `CN_EMAIL` | Email. Used for ssl cert generation. | `support@jans.io` | +| `CN_CITY` | City. Used for ssl cert generation. | `Austin` | +| `CN_STATE` | State. Used for ssl cert generation | `TX` | +| `CN_COUNTRY` | Country. Used for ssl cert generation. | `US` | +| `CN_INSTALL_LDAP` | **NOT SUPPORRTED YET** | `false` | +| `CN_INSTALL_CONFIG_API` | Installs the Config API service. | `true` | +| `CN_INSTALL_SCIM` | Installs the SCIM API service. | `true` | +| `CN_INSTALL_FIDO2` | Installs the FIDO2 API service. | `true` | +| `MYSQL_DATABASE` | MySQL jans database. | `jans` | +| `MYSQL_USER` | MySQL database user. | `jans` | +| `MYSQL_PASSWORD` | MySQL database user password. | `1t5Fin3#security` | +| `MYSQL_HOST` | MySQL host. | `mysql` which is the docker compose service name | + + +## How to run + +Download the compose file + +```bash + +wget https://raw.githubusercontent.com/JanssenProject/jans/main/docker-jans-monolith/jans-mysql-compose.yml +``` + +This docker compose file runs two containers, the janssen monolith container and mysql container. + +```bash +docker compose -f jans-mysql-compose.yml up -d +``` + +To view the containers running + +```bash + +docker compose -f jans-mysql-compose.yml ps +``` + +## Configure Janssen Server + +```bash + +docker compose -f jans-mysql-compose.yml exec jans sh #This opens a bash terminal in the running container + +/opt/jans/jans-cli/config-cli.py #configure using the config-cli + +/opt/jans/jans-cli/scim-cli.py #configure using the scim-cli +``` + +## Access endpoints externally + +Add to your `/etc/hosts` file the ip domain record which should be the ip of the instance docker is installed at and the domain used in the env above `CN_HOSTNAME`. + +```bash +# For-example +172.22.0.3 demoexample.jans.io +``` + +After adding the record you can hit endpoints such as https://demoexample.jans.io/.well-known/openid-configuration + +## Clean up + +Remove setup and volumes + +``` +docker compose -f jans-mysql-compose.yml down +``` diff --git a/docs/admin/install/vm-install/quick-start-install.md b/docs/admin/install/docker-install/quick-start.md similarity index 77% rename from docs/admin/install/vm-install/quick-start-install.md rename to docs/admin/install/docker-install/quick-start.md index 0dff2cc72fc..3da84807414 100644 --- a/docs/admin/install/vm-install/quick-start-install.md +++ b/docs/admin/install/docker-install/quick-start.md @@ -6,13 +6,12 @@ tags: - docker --- -# Docker Based Quick Start Installation +!!! Warning + **This image is for testing and development purposes only. Use Janssen [helm charts](https://github.com/JanssenProject/jans/tree/main/charts/janssen) for production setups.** -The quickest way to get a Janssen Server up and running is to install a Docker container-based fully featured Janssen Server. - -!!! Note +## Overview - This method of installation is suitable only for testing, development, or feature exploration purposes. Not for production deployments. +The quickest way to get a Janssen Server up and running is to install a Docker container-based fully featured Janssen Server. ## System Requirements @@ -20,16 +19,16 @@ System should meet [minimum VM system requirements](vm-requirements.md) ## Install -Run the command given below to start the installation. - Installation depends on a [set of environment variables](https://github.com/JanssenProject/jans/tree/main/docker-jans-monolith#environment-variables). These environment variables can be set to customize installation as per the need. If not set, the installer uses default values. +Run this command to start the installation: + ```bash wget https://raw.githubusercontent.com/JanssenProject/jans/main/automation/startjanssenmonolithdemo.sh && chmod u+x startjanssenmonolithdemo.sh && sudo bash startjanssenmonolithdemo.sh demoexample.jans.io MYSQL ``` -At the end of the process, following messages will confirm that the Janssen server and related services are up and running in respective Docker containers. +Console messages like below confirms the successful installation: ``` [+] Running 3/3 @@ -37,7 +36,7 @@ At the end of the process, following messages will confirm that the Janssen serv ⠿ Container docker-jans-monolith-mysql-1 Started 0.6s ⠿ Container docker-jans-monolith-jans-1 Started 0.9s -Waiting for the Janssen server to come up. Depending on the resources it may take 3-5 mins for the services to be up. +Waiting for the Janssen server to come up. Depending on the resources it may take 3-5 mins for the services to be up. Testing openid-configuration endpoint.. ``` @@ -77,13 +76,13 @@ And then use CLI tools to configure Janssen Server as needed. ## Uninstall / Remove the Janssen Server -This docker based installation uses `docker compose` under the hood to create containers. Hence to uninstalling Janssen server involves invoking `docker compose` with appropriate yml file. Run command below to stop and remove containers. +This docker based installation uses `docker compose` under the hood to create containers. Hence uninstalling Janssen server involves invoking `docker compose` with appropriate yml file. Run command below to stop and remove containers. ``` docker compose -f /tmp/jans/docker-jans-monolith/jans-mysql-compose.yml down && rm -rf jans-* ``` -Console messages like below confirms the successful removal. +Console messages like below confirms the successful removal: ``` [+] Running 3/3 diff --git a/mkdocs.yml b/mkdocs.yml index da779caf344..467fe91633f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -139,16 +139,17 @@ nav: - 'Passwordless Authentication': 'admin/planning/passwordless-auth.md' - 'Machine-to-Machine Authentication': 'admin/planning/machine-to-machine.md' - 'Installation': - - 'admin/install/README.md' - 'VM Installation': - 'admin/install/vm-install/README.md' - 'VM Requirements': 'admin/install/vm-install/vm-requirements.md' - - 'Docker Quick Start': 'admin/install/vm-install/quick-start-install.md' - 'Ubuntu': 'admin/install/vm-install/ubuntu.md' - 'RHEL': 'admin/install/vm-install/rhel.md' - 'Suse': 'admin/install/vm-install/suse.md' # - 'FIPS DISA STIG': 'admin/install/vm-install/disa-stig.md' - 'Dynamic Download': 'admin/install/vm-install/dynamic-download.md' + - 'Docker Installation': + - 'Quick Start': 'admin/install/docker-install/quick-start.md' + - 'Docker compose': 'admin/install/docker-install/compose.md' - 'Helm Deployments': - 'admin/install/helm-install/README.md' - 'Local Kubernetes Cluster': 'admin/install/helm-install/local.md' @@ -157,7 +158,7 @@ nav: # - 'Digital Ocean DOK': 'admin/install/helm-install/digitalocean-dok.md' - 'Microsoft Azure AKS': 'admin/install/helm-install/microsoft-azure.md' # - 'Red Hat Open Shift': 'admin/install/helm-install/red-hat-open-shift.md' - - 'Using Rancher Marketplace': 'admin/install/helm-install/rancher.md' + - 'Using Rancher Marketplace': 'admin/install/helm-install/rancher.md' - 'Setup Instructions': 'admin/install/setup.md' - 'FAQ': 'admin/install/install-faq.md' - 'Kubernetes Operation Guide':