System Overview
Learn the deployment model, system architecture, and AWS deployment resources of the Code Ocean VPC application.
Deployment Model
Code Ocean VPC is installed in your AWS account. It can be installed into a new dedicated AWS VPC which follows AWS Well-Architected guidelines, or into an existing AWS VPC so that you can leverage existing AWS resources and easily align with company VPC guidelines and standards.
Code Ocean VPC deployments are managed with AWS CloudFormation infrastructure as code (IaC) service. A CloudFormation template is available for installation and upgrades and it provisions all AWS resources required to run Code Ocean in your AWS account. See our CloudFormation Deployment section.
System Architecture
Code Ocean is designed to enable secure cross-functional team collaboration while managing a large number of backend services, so you and your colleagues can focus on the research. The following diagram represents the most common system architecture for Code Ocean on AWS environments.
VPC Network
If you choose to install Code Ocean into its own dedicated AWS VPC the CloudFormation template will provision a new VPC across two availability zones with public and private subnets in your selected AWS region. The availability zones and CIDR blocks for VPC and subnets are configurable.
If you choose to install Code Ocean into an existing AWS VPC you can configure the CloudFormation template with the two availability zones and the private and public subnets to deploy to. Public subnets are required if you choose an internet-facing deployment.
Dedicated machines can run across up to six availability zones to provide maximum instance type availability throughout the region. The availability zones and CIDR blocks for the subnets are configurable.
EC2, Batch and ECS
Code Ocean uses an HTTPS-only AWS application load balancer (ALB) to expose the system to users and to allow access to its internal Git server and Docker registry. The ALB can be internet-facing or internal for deployments behind a VPN.
The system manages five types of EC2 instances:
Services - Single machine in an auto-scale group attached to an internal load balancer that runs all internal system services.
Flex Workers - Two auto-scale groups of worker machines where the actual users computations are running. One auto scale group for GPU based computations and the other for general non-GPU computations. When you run a Compute Capsule within Code Ocean it gets scheduled to run on one of the worker machines. The system will automatically provision more worker machines (scale out) as the load increases and deprovision worker machines (scale in) as the load decreases.
Dedicated Machines - Instances launched exclusively to run user computations. Users can select the instance type from a wide range of instance specifications, including spot instance to reduce cost. Administrators can configure the list of available instance specifications.
System Jobs - An AWS Batch ECS cluster of instances designed to run asynchronous, resource intensive system jobs such as the creation and indexing of large data assets. The number and types of instances in the cluster are automatically determined by ECS based on the number of jobs and their resource requirements.
Pipelines - Four AWS Batch ECS clusters of instances that support the execution of Nextflow pipelines, with options for GPU or non-GPU instances, and Spot or On-Demand types. The number and types of instances in the cluster are automatically determined by ECS based on the number of running pipelines and their resource requirements.
The deployment is configured with security groups to control network flow between parts of the system and IAM instance roles for each instance type to limit access to AWS resources.
Shell access to the EC2 instances is available through AWS SSM Session Manager.
AMI
Each version of Code Ocean VPC comes with a dedicated AMI that is specified in the CloudFormation template. The AMI is based on Amazon Linux 2023 and is used for all types of Code Ocean instances. Code Ocean AMIs are shared with customers as soon as the corresponding version is released.
In environments subject to stringent external AMI usage policies, you may instead build your own AMI and override the default by supplying its ID via the custom AMI ID parameter in the CloudFormation template.
ECR
Docker images for Code Ocean services and tools are published to the Code Ocean registry in AWS Public ECR and are automatically pulled by Code Ocean instances, delivering fast, reliable distribution and a consistent container-based microservices architecture.
If you operate under strict security or compliance constraints, you can mirror each release’s docker images into your own private ECR or any OCI-compatible registry by:
Pulling the required images from AWS Public ECR.
Pushing them into your private registry.
Overriding the defaults in the CloudFormation stack by providing your registry’s URI and the access-secret ARN via the Custom Upstream Docker Registry CloudFormation template parameters.
DNS
The system is hosted on a subdomain managed with an AWS Route53 hosted zone. For internet-facing Code Ocean deployments the hosted zone is public, and you will need to delegate to it from your parent or root domain. For internal deployments behind a VPN the Route53 hosted zone will be private. See our Choose a Hosting Domain section for details.
The system also uses an internal Route53 private hosted zone for internal service discovery.
Storage
There are three types of storage medium used:
EBS data volume:
Where most of the internal persistent system data is stored. For example, a Compute Capsule in the system is backed by a git repo which is persisted in this storage type.
The volume is configured with encryption at rest.
S3 buckets:
Used to store input (datasets) and output (results) data of Compute Capsules, as well as the internal docker registry storage and other system persistent storage buckets.
All S3 buckets are private, with server-side encryption, and access logs enabled by default. S3 bucket versioning is enabled on buckets that store persistent data.
EFS:
The Datasets Cache EFS provides a computation (Compute Capsule) running on a worker instance machine with fast access to datasets. Once a dataset is available it is cached on EFS which gets mounted to the worker instance machines.
The Scratch EFS provides a dedicated folder per compute capsule for intermediate data that persists through the lifetime of the capsule.
Encryption at rest is enabled by default on all EFS storage.
Bedrock
The Aqua AI assistant in Code Ocean leverages Amazon Bedrock models to power its LLM agentic capabilities, enabling it to process user prompts, generate responses, and provide intelligent assistance. Aqua comes with a built-in knowledge base to provide Code Ocean expertise and know-how, ensuring Aqua can combine free-form reasoning with knowledge retrieval to deliver accurate and context-aware outputs.
Aqua uses the Anthropic Claude models with cross-region inference profiles. Geographic cross-Region Inference processes requests only within a defined geographic area (such as the US, EU, or APAC) while delivering higher throughput than single-region inference, and helps organizations meet data residency and compliance requirements, as noted in the AWS documentation.
Monitoring
Code Ocean natively reports all metrics to AWS CloudWatch. In addition to metrics from AWS services that Code Ocean uses, such as CPU utilization from EC2 and disk IO metrics from EBS, the system also reports custom metrics to a custom CodeOcean CloudWatch metrics namespace. For example, this includes Code Ocean worker machine utilization, and memory and disk utilization on all machines.
The deployment provisions AWS CloudWatch alarms and an SNS topic to easily get notifications on system issues.
Code Ocean pushes all OS and application logs to CloudWatch Logs. This log data can help with troubleshooting system issue.
Cost and Licenses
As Code Ocean VPC is installed in your AWS account, you are responsible for the cost of the AWS services used while running the Code Ocean VPC deployment.
The AWS CloudFormation template includes configuration parameters that you can customize. Some of these settings, such as instance types, will affect the cost of deployment. For cost estimates, see the pricing pages for each AWS service used in the deployment. AWS prices are subject to change.
Tip: After you deploy the Code Ocean VPC, we recommend that you enable the AWS Cost and Usage Report to track costs associated with the deployment. This report delivers billing metrics to an S3 bucket in your account. It provides cost estimates based on usage throughout each month and finalizes the data at the end of the month. For more information about the report, see the AWS documentation.
This deployment requires a license to run the Code Ocean VPC platform. To obtain a license key, contact Code Ocean by emailing support@codeocean.com.
Support and SLA
Customers can report issues at any time (24x7x365) by sending an email to support@codeocean.com. Code Ocean will make commercially reasonable efforts to respond during normal business hours, based on the severity of the issues, which determines the initial response and target resolution times.
For more information about SLAs and support tiers, please contact us at support@codeocean.com.
Last updated
Was this helpful?