README.md

orca-deploy

Packager project for NCLS Development's Orca solution.

Usage

1. Build and publish a Docker image of the Web server using the instructions found under app/.

2. Deploy the environment either using either:

   • Elastic Beanstalk (see eb/), or
   • directly onto a simple EC2 instance (see ec2/).

   The main difference between these two approaches is the SSL setup.

Tip

Don't forget to compile and publish setup.tag.gz with each release:

tar --directory ec2/setup -czvf setup.tar.gz .

app

This section is used to create and publish a new version of Orca's Web application as a Docker image.

Requirements

You'll need to have both the AWS CLI and the Docker CLI installed and available.
The image will be published to our AWS ECS registry (424880512736.dkr.ecr.eu-west-1.amazonaws.com/orca).

Tip

You will need to have configured a CLI profile named ncls that has write access to ECR on the 424880512736 account.

Usage

• Make sure to have the webapp available under the webapps/ directory
• Execute compose.sh <version>.

eb

Warning

This method doesn't deploy puppeteer-html2pdf, which is required for PDF generation.

This section creates a application bundle for AWS Elastic Beanstalk to run a Multi-Container Docker environment with a ready-to-use Orca Web server.

Using Elastic Beanstalk, the SSL certificates are managed via AWS Certificate Manager (ACM) and installed on a front-facing Elastic Load Balancer (ELB). The distributed certificate is a wildcard, whose renewal is automatically handled by ACM.

Note

• Pro: Easiest setup possible.
• Con: Uses an ELB (per environment), which is somewhat pricy and downright overkill, considering our current needs.

Usage

• Create an Elastic Beanstalk environment configured as follows:
  1. Use an Elastic Load Balancer and listen for both HTTP and HTTPS
  2. Select Multi-Container Docker environment
  3. Set up the required environment variables
• Create a zip archive from the Dockerrun.aws.json and the nginx-config directory.
• Upload to the desired Elastic Beanstalk environment.

ec2

This section guides you through setting up client configuration and building tools to deploy Orca directly onto an EC2 instance.

Managing your own EC2 instance "manually" will use certificates issued by Let's Encrypt.

Note

• Pro: No additional costs, other than the EC2 instance and data transfer.
• Con: More complex setup.

Usage

1. Launch an EC2 instance configured as follows:

• Choose an instance of type Amazon Linux 2023 AMI (e.g.: ami-0fc3317b37c1269d3).

• Pick a preconfigured Security Group that opens HTTP (:80/tcp), HTTPS (:443/tcp) and SSH (:22/tcp).

  • Also ensure that [::]:80, [::]:443 and [::]:22 are open, for IPv6 support.

• Grant it the ec2-orca-install IAM Role that allows:

  Policy	Service	Reason
  AmazonEC2ReadOnlyAccess	EC2	List instance tags
  AmazonS3ReadOnlyAccess	S3	Get client-specific configuration
  AmazonEC2ContainerRegistryReadOnly	ECR	Access Orca's docker container

2. Create the DNS record for <client id>.orca-solution.com pointing to the right instance (use an Elastic IP).

3. Set the expected environment variables:

   • Edit the configuration template
   • Upload it as <client id>.conf in the orca-clients S3 bucket (arn:aws:s3:::orca-clients).

4. Connect onto the machine and install the latest release via the setup script on master branch:

   ssh -i /path/to/key.pem ec2-user@<client-id>.orca-solution.com
   bash <(curl -s https://raw.githubusercontent.com/ccjmne/orca-deploy/pre-revamp/ec2/utils/deploy.sh)

Tip

Ensure the DNS records have properly propagated before proceeding to step 4.

Update Orca

Use the update.sh script installed during the deployment in your home directory (/home/ec2-user) as follows:

./update.sh <version>

Where <version> corresponds to a tag for our web app's Docker container and defaults to latest.

Create new versions of the setup script

Create a new release on GitHub and upload the setup.tar.gz archive as an asset, generated as follows:

tar --directory setup -czvf setup.tar.gz .

Environment variables

Name	Description
AWS_ACCESS_KEY_ID*	Access Key ID of user with full access to arn:aws:s3:::orca-resources
AWS_SECRET_KEY*	Secret Key of user with full access to arn:aws:s3:::orca-resources
ORCA_DB_HOST*	RDS hostname
ORCA_DB_NAME*	RDS database name
ORCA_DB_USER*	Database user name
ORCA_DB_PASS*	Database user password
ORCA_DEMO_ENABLED	true iff the demo mode should be enabled
ORCA_INIT_SECRET	Used to trigger a (re)initialisation of the database or a demo data reset
CORS_ORIGIN	Used to set the Access-Control-Allow-Origin header

* - Required