Merge pull request #152 from browserstack/testing_manually

Adding docs for local setup

Author: vedharish

Dockerfile

@@ -16,11 +16,13 @@ RUN DEBIAN_FRONTEND=noninteractive \
 # Set env variables used in this Dockerfile (add a unique prefix, such as DEV)
 RUN apt update && apt install -y netcat dnsutils libmariadbclient-dev
 
+RUN mkdir -p /ebs/logs && touch /ebs/logs/engima.log && chmod 777 /ebs/logs/engima.log
+
 ARG APPUID=1001
 RUN useradd -rm -d /home/app -s /bin/bash -g root -G sudo -u "$APPUID" app
 WORKDIR /srv/code/dev
 RUN mkdir -p logs
-RUN chown -R app /srv/code/dev
+RUN chown -R app /srv/code/dev /ebs
 USER app
 
 

Makefile

@@ -24,9 +24,16 @@ dev: setup_mounts
 
 ## make build : Build and start docker containers - (web and db)
 .PHONY: build
+build: export APPUID = $(APP_UID)
 build:
 	@docker-compose up --build -d web
 
+## make build_only : Only build the web container
+.PHONY: build_only
+build_only: export APPUID = $(APP_UID)
+build_only:
+	@docker-compose build web
+
 .PHONY: down
 down: export APPUID = $(APP_UID)
 down:
@@ -73,4 +80,4 @@ schema_validate:
 	@echo $(shell python3 scripts/clone_access_modules.py && python3 scripts/validator.py)
 
 run_semgrep:
-	$(shell semgrep --error --config "p/cwe-top-25" --config "p/owasp-top-ten" --config "p/r2c-security-audit")
+	$(shell semgrep --error --config "p/cwe-top-25" --config "p/r2c-security-audit")

README.md

@@ -1,7 +1,49 @@
-# enigma-public-central
-Central Codebase for access management tool
+## Enigma Access Management
 
-### For contributing code
+![BrowserStack Logo](https://d98b8t1nnulk5.cloudfront.net/production/images/layout/logo-header.png?1469004780)
+
+This tool consists of 2 different components: a central webserver and pluggable access modules.
+
+This repo is the code-base for the central webserver.
+Refer to [this](https://github.com/browserstack/enigma-public-access-modules) for published access modules with this tool.
+
+Refer to [this doc](/docs/%E2%80%9CHow-to%E2%80%9D%20guides/Adding%20Modules.md) on how to create custom access modules
+
+## Usage
+
+The following steps are for hosting Enigma locally from published docker container images.
+
+For development setup, follow this [doc](/docs/one-click-dev.md)
+
+### Pre-requisistes
+
+You will need to have docker daemon running locally to run the published containers.
+If you don't have docker setup, follow the guidelines [here](https://docs.docker.com/get-docker/)
+
+### Steps
+
+1. Ensure you have a valid `config.json` present locally.
+
+The default [config.json.sample](https://github.com/browserstack/enigma-public-central/blob/main/config.json.sample) should be sufficient to start.
+
+You can then add module-specific configuration for the modules you want integrated with Enigma.
+For detailed instructions on configuration, follow [this doc](/docs/Configuration%20Guide.md)
+
+2. Run the enigma docker container by mounting the downloaded config to the container
+
+```bash
+docker run --rm --name enigma -p 8000:8000 -v "$(pwd)/config.json":/srv/code/dev/config.json browserstack/enigma:v1
+```
+
+Ensure that you 8000 port is free to use, and ensure that path to config.json is correct.
+
+That's it! Enigma should be running locally on port 8000
+
+
+For first time user sign-in, follow [this doc](/docs/%E2%80%9CHow-to%E2%80%9D%20guides/User%20Guides/First%20User%20Setup.md)
+
+
+## Contributing code
 
 - Python 3.11.0
 - pre-commit (see rules [below](#rules-enforced-by-the-pre-commit-hooks))
@@ -11,7 +53,7 @@ Central Codebase for access management tool
   - run: `pre-commit autoupdate`
   - run: `pre-commit run --all-files --show-diff-on-failure --color always`
 
-## Commit Message Guideline
+### Commit Message Guideline
 
 Format: `<type>(<scope>): <subject>`
 
@@ -32,7 +74,7 @@ Format: `<type>(<scope>): <subject>`
 - `perf`: a code change that improves performance
 - `revert`: revert to a commit
 
-## Example
+### Example
 
 ```
 feat: add hat wobble

config.json.sample

@@ -1,6 +1,6 @@
 {
   "django_setup": {
-    "SECRET_KEY": "",
+    "SECRET_KEY": "random_secret_that_you_should_change_on_production",
     "DEBUG": false,
     "ALLOWED_HOSTS": [
       "localhost"

docker-compose.yml

@@ -2,6 +2,7 @@ version: '3'
 services:
   web:
     container_name: dev
+    image: browserstack/enigma:v1
     build:
       context: .
       dockerfile: Dockerfile
@@ -19,9 +20,6 @@ services:
     - 8000:8000
     depends_on:
     - db
-    command: >
-      bash -c "echo Starting Django runserver;
-      python manage.py runserver --insecure 0.0.0.0:8000"
   db:
     container_name: db
     image: mysql/mysql-server:8.0.31

docker-entrypoint.sh

@@ -3,6 +3,17 @@
 LOG_FILE=/ebs/logs/enigma.log
 CONTAINER_HASH=$(echo $RANDOM | md5sum | head -c 20)
 
+trap ctrl_c INT
+
+pid_to_kill=1
+should_continue=0
+
+function ctrl_c() {
+  echo "===== Stopping Service with pid $pid_to_kill ====="
+  kill $pid_to_kill
+  should_continue=1
+}
+
 function log() {
   echo "$(date): $CONTAINER_HASH $@" 2>&1 | tee -a $LOG_FILE
 }
@@ -34,4 +45,18 @@ log "===== Ensure Logs ====="
 touch /ebs/logs/enigma.log
 
 log "===== Running Service ====="
-eval "$@" 2>&1 | prepend
+if [ "$#" -ne 0 ]; then
+  eval "$@" 2>&1 | prepend
+else
+  echo "===== Starting Webserver ====="
+  python manage.py runserver --insecure 0.0.0.0:8000 2>&1 &
+  pid_to_kill=$!
+  echo "Server PID $pid_to_kill"
+
+  while true; do
+    if [ "$should_continue" -ne 0 ]; then
+      break
+    fi
+    sleep 5
+  done
+fi

docs/“How-to” guides/Adding Modules.md

@@ -1,4 +1,4 @@
-This document describes how to add modules on Enigma.
+# How to add modules on Enigma.
 
 Enigma’s access management is built on modules, which refer to the resources/applications the user requires.
 Each module needs to be added and integrated with Enigma's central code in order to provide access for the user.
@@ -12,7 +12,10 @@ Enigma provides the following modules as part of its default settings, these can
 6. Slack
 7. Zoom
 
-When a new resource is required, it's corresponding module has to be added in [Engima's modules repository](https://github.com/browserstack/enigma-public-access-modules.git) or it's own (as per the usecase):
+## Creating custom access modules
+
+When a new resource is required, it's corresponding module has to be added in [Engima's modules repository](https://github.com/browserstack/enigma-public-access-modules.git) or a new dedicated repo (as per the usecase):
+
 - Add `__init__.py`:
 
     ```bash

docs/“How-to” guides/Adding Users.md

@@ -1,27 +1,40 @@
-This document describes how to add users on Enigma.
+# How to add users on Enigma
 
-## Create users on Enigma:
-1. Manual Creation:
+## Manual Creation
 
-    To manually create a user, login as superuser into the admin portal:
+To manually create a user, login as superuser into the admin portal:
 
-    (i) Add user in "Authentication and Authorization administration".
+- Add user in "Authentication and Authorization administration" section.
 
-        ``` Set email to user email id and password to anything you want. Save user details. ```
+Set email to user email id and password to anything you want. Save user details.
 
-    (ii) Add new user in "Access" and save.
+- Add new user in "Access" and save.
 
-    (iii) The user can now log on to Enigma using the credentials set in Step (i)
-2. Google SSO:
-    ### Add the config of googleapi in `config.json`
-    ```bash
-    ....
-    "sso": {
-        "googleapi": {
-            "SOCIAL_AUTH_GOOGLE_OAUTH2_KEY": "<your_google_auth_key>",
-            "SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET": "<your_google_auth_secret>"
-        }
+- The user can now log on to Enigma using the credentials.
+
+## Allow all users to sign-in with Google SSO
+
+### Obtain google OAuth key and secret
+
+Follow the steps [here](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred) to generate `client_secret.json` file.
+
+
+The content of the file will have `client_id` key in `web` section. This is `SOCIAL_AUTH_GOOGLE_OAUTH2_KEY` in the below config.
+
+
+The value for `client_secret` in `web` section is for `SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET`.
+
+### Add the config of googleapi in `config.json`
+
+```bash
+....
+"sso": {
+    "googleapi": {
+        "SOCIAL_AUTH_GOOGLE_OAUTH2_KEY": "<your_google_auth_key>",
+        "SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET": "<your_google_auth_secret>"
     }
-    ....
-    ```
+}
+....
+```
+
 Sign in to enigma using your Google Mail to create a user on Enigma.

docs/“How-to” guides/User Guides/First User Setup.md

@@ -0,0 +1,36 @@
+# First User Setup
+
+To setup admin user on enigma, follow these steps:
+
+1. Setup django superuser
+
+- Exec into the Enigma container
+
+```bash
+docker exec -it enigma bash
+```
+
+- Run the following command in the container to create a superuser
+
+```bash
+python manage.py createsuperuser
+```
+
+- Fill in the `username`, `email` and `password` for admin user
+
+Detailed instructions are available [here](https://docs.djangoproject.com/en/1.8/intro/tutorial02/#creating-an-admin-user)
+
+2. Sign-in into the admin site
+
+- Login to the admin site with the credentials created above.
+
+The admin site should be available at `/admin` with the base url on which enigma is hosted.
+
+This will be `http://localhost:8000/admin` if you are running this locally
+
+3. Now you can view the Enigma app dashboard, by navigating to enigma url.
+
+This will be `http://localhost:8000/` if you are running this locally
+
+
+To create additional users, follow the doc [here](/docs/%E2%80%9CHow-to%E2%80%9D%20guides/Managing%20Groups/Adding%20Users.md)

scripts/clone_access_modules.py

@@ -30,7 +30,6 @@
     if not os.path.exists(requirements_file):
           open(requirements_file, 'w').close()
 
-    print("All urls: %s" % (",".join(urls)))
     for url in urls:
         specified_branch = None
         if "#" in url: