Prerequisites

Docker is used to develop, test, and improve an environment.

1. Install docker
2. Install docker-compose if you are using Linux
3. Install python (version 3.8)
4. Install pipenv (python package manager)
5. Install Node (version 12+)
6. Install yarn (version 1.22.+)
7. Install AWS CLI (version 1.22.+)

Installation

Easy way

make setup & ☕

You will find a more detailed documentation in ./frontend/schemaCMS, ./frontend/schemaUI, ./backend/app and ./docs

Running locally

1. Create Auth0 tenant for local use. You can find instructions here.

2. Copy local.env-example file as local.env and fill missing Auth0 envs using values from your tenant:

   cp local.env-example local.env

3. Run backend services:

   make up

   NOTE: Check if you have any running containers using the same ports as Schema CMS components, if yes please stop/kill those; you can check running containers using a docker ps command and stop/kill selected container using docker stop/kill CONTAINER ID

4. Run frontend:

   make fe-up

Development

Backend is running on localhost:8000

MailCatcher is running on localhost:1080

Documentations is running on localhost:8001

Frontend is running on localhost:3000

Inviting user to Schema CMS localy

1. In a new browser tab go to http://localhost:1080/

2. In a second tab open http://localhost:8000/admin/ and login as a root user, you can set a root password in the local.env, changing value of DJANGO_ROOT_PASSWORD but the default password is set to root12345

3. Now go to a Users tab and click the INVITE USER button, fill all required fields and SAVE.

   NOTE: You can use dummy email if you want because locally we don't send any emails.

4. Go to a tab from step 1. You should see an invitation email with a password change link. Click it and set the password.

5. After the password is set you can go to the http://localhost:3000 and login using invited user credentials.

   NOTE: You won't be able to login to app if you don't set password.

   NOTE: If Gmail email address was used you can log-in to app using Sign in with Google option.

Changing user role

1. Go to the http://localhost:8000/admin/ -> Users
2. click on the user whose role you want to change
3. in a Permissions section you will find a dropdown with available roles, choose one and SAVE
4. after the role was changed you need to login again

API Usage

Available API calls are listed on this page

Deployment

Intro

This project uses AWS CDK for easy deployment application on any AWS account.

To easy manage multiple AWS accounts project uses aws-vault.

Application requires Auth0 and domain with verified certificate in AWS.

Configuration

Prerequisites

1. Make sure you run make setup and you have all packages installed.
2. aws-vault installed.
3. Create and configure Auth0 or Okta identity provider tenant depending what you want to use. You can find instructions for Auth0 here and Okta here.

aws-vault configuration

1. Log In to AWS Console, go to My security credentials and create access key.
2. Use created access key to add new profile in aws-vault.
3. Edit file ~/.aws/config by adding line region=<selected-deployment-region> under profile you added.
4. Update profile and region in .project_config.json.

DockerHub credentials

Since DockerHub limited pulling images for non-register users we need use logged user during deploying SchemaCMS, thats why before deployment we need add in AWS Secrets Manager two secrets: DOCKER_USERNAME and DOCKER_PASSWORD. DockerHub account is available to create here.

Steps

Deploy base resources and components

From project root directory:

1. make deploy-infra
2. make deploy-components

Validate certificates

1. Go to AWS Certificate Manager on selected region.

2. Validate certificate using DNS. You can follow this guide.

   NOTE: As domain names please enter two records. First is just your domain name and second is wild card name with asterisk (*.example.com), this allow protect all subdomains.

3. Wait till status is Issued.

Verify Domain in Amazon Simple Email Service

Amazon Simple Email Service is used by Schema CMS to send emails. Unfortunately AWS SES is in Sandbox mode as default and because of that you can only send mail to and from verified email addresses and domains. User has to request a change from Sandbox to Production mode. For more information look here. But before that at least one domain has to be verified. To do that follow this steps:

1. Go to AWS SES on selected region.
2. Follow this guide.
3. When domain Verification Status will change to verified you have to request moving out from Sandbox mode.

NOTE: Processing this request may take up to 2 days, depending which tier of AWS Support your account is using.

NOTE: Before AWS SES will be moved to Production mode mails can be send only to verified email addresses. You can verify emails following this guide

Create SSN parameters

1. Copy file infra/ssm_parameters.example.json as infra/ssm_parameters.json.
2. Fill parameters values.
   • /schema-cms-app/CERTIFICATE_ARN - use ARN of certificate validated in previous step. You can find it in Details of your this certificate here.
   • /schema-cms-app/DJANGO_DEBUG - on if you want to see debug messages when error happens off if not.
   • /schema-cms-app/DJANGO_DEFAULT_FROM_EMAIL - Verified domain email address that will be used to send emails for example [email protected].
   • /schema-cms-app/DOMAIN_NAME - Domain that will be used to deploy Schema CMS e.g, example.com.
   • /schema-cms-app/DJANGO_HOST - Domain with https:// e.g, https://example.com.
   • /schema-cms-app/DJANGO_WEBAPP_HOST - At this moment same value as DJANGO_HOST.
   • /schema-cms-app/PUBLIC_API_URL - Subdomain api e.g, https://api.example.com/ with / on the end.
   • /schema-cms-app/DJANGO_ROOT_PASSWORD - Your password do django admin console.
   • /schema-cms-app/DJANGO_USER_MGMT_BACKEND - Set schemacms.users.backend_management.auth0.Auth0UserManagement if you want to use Auth0 as identity provider or schemacms.users.backend_management.okta.OktaUserManagement if you want use Okta.
   • /schema-cms-app/DJANGO_SOCIAL_AUTH_AUTH0_DOMAIN - Empty string if you be using Okta else set here domain from created Auth0 SINGLE PAGE APPLICATION.
   • /schema-cms-app/DJANGO_SOCIAL_AUTH_AUTH0_KEY" - Empty string if you be using Okta else set here client ID from created Auth0 SINGLE PAGE APPLICATION.
   • /schema-cms-app/DJANGO_SOCIAL_AUTH_AUTH0_SECRET" - Empty string if you be using Okta else set here client Secret from created Auth0 SINGLE PAGE APPLICATION.
   • /schema-cms-app/DJANGO_USER_MGMT_AUTH0_DOMAIN - Empty string if you be using Okta else set here domain from created Auth0 MACHINE TO MACHINE.
   • /schema-cms-app/DJANGO_USER_MGMT_AUTH0_KEY - Empty string if you be using Okta else set here client ID from created Auth0 MACHINE TO MACHINE.
   • /schema-cms-app/DJANGO_USER_MGMT_AUTH0_SECRET - Empty string if you be using Okta else set here client Secret from created Auth0 MACHINE TO MACHINE.
   • /schema-cms-app/SOCIAL_AUTH_OKTA_OAUTH2_KEY - Empty string if you be using Auth0 else set here client key from web app created in Okta.
   • /schema-cms-app/SOCIAL_AUTH_OKTA_OAUTH2_SECRET - Empty string if you be using Auth0 else set here client secret from web app created in Okta.
   • /schema-cms-app/OKTA_DOMAIN_URL - Empty string if you be using Auth0 else set here domain url to your Okta instance, for example https://dev-7777777.okta.com.
   • /schema-cms-app/OKTA_API_TOKEN - Empty string if you be using Auth0 else set here created API token to your instance.

Deploy application

From project root directory:

1. Run make build to create and push docker images with application to AWS ECR. This step may take some time.
2. After successful build run make deploy-app. This step may take some time.
3. When deploy-app step is done, you need find Load Balancer DNS name record in outputs, that looks similar to:
   • schema-cms-api.ApiServiceLoadBalancerDNSBF9EB7FC = schem-ApiSe-1PMWRS8JQDZ21-901620558.us-west-2.elb.amazonaws.com
   • or go to list of load balancers on selected region in AWS Console and copy DNS name from Schema load balancer
4. Add to your DNS CNAME records pointing your domain and api subdomain to Load Balancer DNS name.

Updating Schema CMS version

During first deployment AWS CodePipeline and AWS CodeBuild were deployed. Those services allow easily deploy selected branch,tag, commit etc. of Schema CMS. To deploy selected version of Schema CMS:

1. Go to AWS CodeBuild on region where Schema CMS was deployed.
2. Enter to SchemaCMS build project.
3. Click Start build.
4. Put version you want deploy in Source version - optional filed.
5. Click Start build.

App will start deploying after couple of seconds. To monitor progress of deployment go to AWS CodePipeline and enter schema-cms-pipeline.

NOTE: When Build stage is done next Deploy stage needs manual approval to run. Approve button will appear on approve changes block. Approve to finish deployment. .

Debugging

To see logs you can use Cloud Watch to monitor the logs for Lambda functions and the Django application.

Building Simplified Deployment Assets

After new SchemaCMS version is released to master.

Build backend public image:

cd backend/app
aws-vault exec <profile to base schema aws account> -- make push-image-to-public-repo

Build frontend public image:

cd nginx
aws-vault exec <profile to base schema aws account> -- make push-image-to-public-repo

Build workers lambda zip:

cd backend/functions/workeres
make pack
aws-vault exec <profile to base schema aws account> -- make push-to-public

Build workers lambda zip:

cd backend/functions/image_resize
make pack
aws-vault exec <profile to base schema aws account> -- make push-to-public