From d7dd454bb4913ddb50534789670350e625cfabe5 Mon Sep 17 00:00:00 2001 From: Gavin Elder Date: Mon, 22 Dec 2025 22:05:13 +0000 Subject: [PATCH 1/5] docs: refactor enterprise installation docs --- personas/devops-persona.md | 190 ++++++++++ .../enterprise-sidebar.json | 45 ++- .../aws-ecs-cloudformation.json | 353 ------------------ .../cloudformation/params.json.template | 54 --- .../enterprise/_templates/k8s/dbconsole.yml | 34 -- .../advanced-topics/cloudformation.md | 70 ---- .../enterprise/configuration/mirroring.md | 44 +++ .../enterprise/configuration/wave.md | 88 ++++- .../enterprise/docker-compose.md | 29 +- platform-enterprise_docs/enterprise/helm.md | 9 +- .../enterprise/kubernetes.md | 169 +++------ .../enterprise/overview.md | 2 +- .../enterprise/prerequisites/aws.md | 175 --------- .../enterprise/prerequisites/azure.md | 284 -------------- .../enterprise/prerequisites/common.md | 107 ------ .../enterprise/prerequisites/gcp.md | 160 -------- .../enterprise/prerequisites/on-prem.md | 46 --- .../enterprise/studios-docker-compose.md | 85 +++++ .../enterprise/studios-kubernetes.md | 123 ++++++ 19 files changed, 612 insertions(+), 1455 deletions(-) create mode 100644 personas/devops-persona.md delete mode 100644 platform-enterprise_docs/enterprise/_templates/cloudformation/aws-ecs-cloudformation.json delete mode 100644 platform-enterprise_docs/enterprise/_templates/cloudformation/params.json.template delete mode 100644 platform-enterprise_docs/enterprise/_templates/k8s/dbconsole.yml delete mode 100644 platform-enterprise_docs/enterprise/advanced-topics/cloudformation.md create mode 100644 platform-enterprise_docs/enterprise/configuration/mirroring.md delete mode 100644 platform-enterprise_docs/enterprise/prerequisites/aws.md delete mode 100644 platform-enterprise_docs/enterprise/prerequisites/azure.md delete mode 100644 platform-enterprise_docs/enterprise/prerequisites/common.md delete mode 100644 platform-enterprise_docs/enterprise/prerequisites/gcp.md delete mode 100644 platform-enterprise_docs/enterprise/prerequisites/on-prem.md create mode 100644 platform-enterprise_docs/enterprise/studios-docker-compose.md create mode 100644 platform-enterprise_docs/enterprise/studios-kubernetes.md diff --git a/personas/devops-persona.md b/personas/devops-persona.md new file mode 100644 index 000000000..1e248b2c2 --- /dev/null +++ b/personas/devops-persona.md @@ -0,0 +1,190 @@ + + + +## Background + + +Seqera documentation related to platform operations currently accommodates multiple skill levels and includes extensive supporting information about third-party systems. This approach results in documentation that contains more foundational content than is typically found in other enterprise products. + +When writing documentation for enterprise customers, focused content is more valuable than comprehensive coverage of tangential topics. By minimizing supporting documentation for third-party systems we don't control and assuming baseline reader knowledge, we can write more focused, relevant documentation about Seqera's products and platforms. + +This approach enables us to maintain documentation that serves our intended audience experienced infrastructure professionals while reducing the maintenance burden of keeping third-party system guidance current. + +**For customers who lack the requisite knowledge and skills**, several support options are available: + +- **Cloud Vendor & supplier documentation** \- All cloud vendors provide up to date detailed documentation for how to deploy and run their services. + - AWS + - [Setting up ElastiCache](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/set-up.html) + - [Amazon RDS for MySQL \- Amazon Relational Database Service](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_MySQL.html) + - GCP + - [MySQL on Compute Engine | Google Cloud Documentation](https://docs.cloud.google.com/compute/docs/instances/mysql/discover-mysql) + - [Memorystore: in-memory Redis compatible data store | Google Cloud](https://cloud.google.com/memorystore?hl=en) + - Azure + - [Azure Cache for Redis | Microsoft Azure](https://azure.microsoft.com/en-us/products/cache) + - [Azure Database for MySQL documentation | Microsoft Learn](https://learn.microsoft.com/en-us/azure/mysql/) + - Redis + - [Install on Kubernetes | Docs](https://redis.io/docs/latest/operate/redisinsight/install/install-on-k8s/) + - MySQL + - [MySQL Operator for Kubernetes Manual](https://dev.mysql.com/doc/mysql-operator/en/) +- **Seqera Professional Services** provides training and implementation support +- **Seqera Cloud** provides a fully managed alternative for organizations without the resources to run enterprise systems in-house + +## Examples + +**Wave installation documentation** provides a clear model for this approach. We specify prerequisites for installation and allow readers to install those dependencies before proceeding with the Wave installation itself. This keeps the documentation focused on Wave. + +**Platform installation documentation** currently takes a different approach. We guide readers through the installation of prerequisites, which shifts focus away from the Seqera Platform installation itself. This results in longer documentation that mixes Seqera-specific guidance with general infrastructure setup. + +**The gap:** Our intent is to provide deeper technical articles and tooling specific to Seqera products. However, it's not feasible to provide comprehensive coverage of how all dependencies work. Instead, we should make the core assumption that readers understand these foundational systems and focus our documentation on how Seqera integrates with them. + +## Guiding Principle + +**_Seqera is the client, not the server._** + +Document what Seqera needs from infrastructure, not how to build that infrastructure. + +This principle keeps documentation focused on the integration contract rather than becoming a general infrastructure guide. + +## Assumptions + +Our documentation assumes readers have: + +- Working knowledge of their chosen cloud provider (AWS, Azure, GCP) +- Familiarity with container orchestration if deploying on Kubernetes +- Basic understanding of infrastructure components (databases, caching, networking) +- Access to internal or external resources for foundational training + +--- + +## Scope Definition + +### In Scope + +| Category | Description | Example | +| :--------------------------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | +| **Technical requirements** | Clearly specify what Seqera Platform needs to operate | "Seqera requires Redis 6.2+" | +| **Credential creation** | How to create credentials for Seqera to connect to services | "Create a Kubernetes service account with these permissions" | +| **Configuration** | Seqera-specific environment variables and settings | `TOWER_REDIS_URL`, `TOWER_DB_URL` | +| **Integration points** | How Seqera connects to third-party services | "Configure OIDC callback URL in your identity provider" | +| **Platform-specific tuning** | Resource allocations, metrics, and optimization for Seqera | "Recommended JVM heap size for your workload profile" | +| **Links to authoritative sources** | References to official third-party documentation | "See [Kubernetes RBAC documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)" | + +### Out of Scope + +| Category | Description | Example | +| :------------------------------ | :------------------------------------------------ | :------------------------------------------------ | +| **Infrastructure installation** | Step-by-step guides for deploying prerequisites | Redis manifests, Kubernetes cluster creation | +| **Service administration** | How to operate and maintain third-party services | Redis clustering, database optimization | +| **General tooling tutorials** | Educational content on third-party tools | How to write PromQL queries, kubectl basics | +| **Cloud provider setup** | Infrastructure provisioning in cloud environments | Creating VPCs, configuring IAM roles from scratch | +| **Foundational training** | Basic concepts for infrastructure technologies | "What is Kubernetes?", Docker fundamentals | + +--- + +## Explicit Examples + +### In Scope vs Out of Scope + +| In Scope | Out of Scope | +| :---------------------------------------------------------------------- | :--------------------------------------------------- | +| "Create a Kubernetes service account with these permissions for Seqera" | "How to create a Kubernetes cluster" | +| "Configure `TOWER_REDIS_URL` to connect to your Redis instance" | "Here's a Redis manifest to deploy Redis" | +| "Your database must support PostgreSQL 11+" | "How to install and configure PostgreSQL" | +| "Seqera requires these IAM permissions" (policy JSON provided) | "How to navigate the AWS IAM console" | +| "Configure your ingress to route to the Seqera service" | "How to install and configure an ingress controller" | + +### Service-Specific Guidance + +#### Redis + +- **In scope**: Version requirements (6.2+), connection variables (`TOWER_REDIS_URL`), TLS configuration for Seqera +- **Out of scope**: Redis deployment manifests, clustering setup, memory optimization + +#### Kubernetes + +- **In scope**: Required RBAC permissions, service account configuration, resource requests for Seqera pods +- **Out of scope**: Cluster provisioning, StorageClass tutorials, general kubectl usage + +#### Databases + +- **In scope**: Schema requirements, connection string format, supported versions +- **Out of scope**: Database installation, backup strategies, query optimization + +#### Authentication Providers + +- **In scope**: Callback URL format, required claims/scopes, Seqera environment variables +- **Out of scope**: How to set up Keycloak/Okta/Entra ID from scratch + +--- + +## Rationale + +### Benefits + +| Benefit | Description | +| :---------------------------------- | :------------------------------------------------------------------------------------------------ | +| **Reduced maintenance burden** | Third-party UIs and CLIs change frequently; linking to authoritative sources avoids version drift | +| **Clear ownership** | Seqera documentation covers Seqera; third-party documentation covers third-party tools | +| **Faster navigation** | Technical users find Seqera-specific guidance without wading through familiar content | +| **Professional Services alignment** | Customers requiring foundational training engage pre-sales and PS teams | +| **Documentation authority** | Seqera docs become the definitive source for Platform-specific knowledge | + +### Target Audience + +This approach assumes our readers are: + +- DevOps engineers with infrastructure experience +- Platform engineers responsible for deployment +- Technical teams evaluating or implementing Seqera + +Users requiring foundational knowledge in prerequisite technologies can access training through Seqera's pre-sales and professional services teams. + +--- + +## Writing Guidelines + +### When documenting integrations + +1. **State the requirement** — What does Seqera need? +2. **Provide the configuration** — Which variables/settings connect Seqera to the service? +3. **Link to authoritative sources** — Where can users learn more about the third-party component? + +### Template + +``` +## [Service Name] Integration + +### Requirements + +Seqera Platform requires [service] version X.X or later. + +### Configuration + +| Variable | Description | +| ------------------------ | ---------------------------- | +| `TOWER_SERVICE_URL` | Connection URL for [service] | +| `TOWER_SERVICE_PASSWORD` | Authentication credential | + +### Additional Resources + +See [Official Service Documentation](https://example.com) for installation and configuration guidance. +``` + +### Avoid + +- Step-by-step console navigation for third-party services +- Screenshots of third-party UIs (they change frequently) +- Manifests or deployment files for prerequisite services +- Explanations of basic concepts users should already understand + +--- + +## Exemplary Sections + +These existing documentation sections demonstrate the proposed approach: + +- **Monitoring guide** — Focuses on Seqera-specific metrics and alerting +- **Production checklist** — Provides Seqera recommendations with links to external resources +- **Configuration reference** — Comprehensive coverage of Seqera environment variables + +Use these as templates when refactoring other sections. diff --git a/platform-enterprise_docs/enterprise-sidebar.json b/platform-enterprise_docs/enterprise-sidebar.json index 21509dca0..6ae5ac8b0 100644 --- a/platform-enterprise_docs/enterprise-sidebar.json +++ b/platform-enterprise_docs/enterprise-sidebar.json @@ -12,42 +12,49 @@ "items": [ { "type": "category", - "label": "Prerequisites", + "label": "Platform", "collapsed": true, "items": [ - "enterprise/prerequisites/aws", - "enterprise/prerequisites/azure", - "enterprise/prerequisites/gcp", - "enterprise/prerequisites/on-prem" + "enterprise/docker-compose", + "enterprise/kubernetes", + "enterprise/helm" ] }, { "type": "category", - "label": "Configuration", + "label": "Studios", "collapsed": true, "items": [ - "enterprise/configuration/overview", - "enterprise/configuration/authentication", - "enterprise/configuration/aws_parameter_store", - "enterprise/configuration/networking", - "enterprise/configuration/reverse_proxy", - "enterprise/configuration/ssl_tls", - "enterprise/configuration/pipeline_optimization", - "enterprise/configuration/wave", + "enterprise/studios-docker-compose", + "enterprise/studios-kubernetes", "enterprise/studios" ] }, { "type": "category", - "label": "Deployment", + "label": "Pipeline optimization", "collapsed": true, "items": [ - "enterprise/docker-compose", - "enterprise/kubernetes", - "enterprise/testing", - "enterprise/upgrade" + "enterprise/configuration/pipeline_optimization" + ] + }, + { + "type": "category", + "label": "Configuration", + "collapsed": true, + "items": [ + "enterprise/configuration/overview", + "enterprise/configuration/authentication", + "enterprise/configuration/networking", + "enterprise/configuration/ssl_tls", + "enterprise/configuration/reverse_proxy", + "enterprise/configuration/aws_parameter_store", + "enterprise/configuration/wave", + "enterprise/configuration/mirroring" ] }, + "enterprise/testing", + "enterprise/upgrade", { "type": "category", "label": "Advanced", diff --git a/platform-enterprise_docs/enterprise/_templates/cloudformation/aws-ecs-cloudformation.json b/platform-enterprise_docs/enterprise/_templates/cloudformation/aws-ecs-cloudformation.json deleted file mode 100644 index 123166df2..000000000 --- a/platform-enterprise_docs/enterprise/_templates/cloudformation/aws-ecs-cloudformation.json +++ /dev/null @@ -1,353 +0,0 @@ -{ - "AWSTemplateFormatVersion" : "2010-09-09", - "Description" : "Nextflow Tower ECS template", - "Parameters": { - "ClusterName": { - "Type": "String", - "Description": "ECS cluster name" - }, - "TowerSmtpHost": { - "Type": "String", - "Description": "SMTP server hostname" - }, - "TowerSmtpPort": { - "Type": "String", - "Description": "SMTP server port" - }, - "TowerSmtpUser": { - "Type": "String", - "Description": "SMTP server username", - "NoEcho": "true" - }, - "TowerSmtpPassword": { - "Type": "String", - "Description": "SMTP server password", - "NoEcho": "true" - }, - "TowerContactEmail": { - "Type": "String", - "Description": "Email for login emails" - }, - "TowerServerUrl": { - "Type": "String", - "Description": "IP address of container instance" - }, - "TowerJwtSecret": { - "Type": "String", - "Description": ">256 bit random string", - "NoEcho": "true" - }, - "TowerCryptoSecretkey": { - "Type": "String", - "Description": ">256 bit random string", - "NoEcho": "true" - }, - "TowerLicense": { - "Type": "String", - "Description": "The Tower License", - "NoEcho": "true" - }, - "TowerDbUrl": { - "Type": "String", - "Description": "MySQL DB connection URL" - }, - "TowerDbUser": { - "Type": "String", - "Description": "MySQL DB username" - }, - "TowerDbPassword": { - "Type": "String", - "Description": "MySQL DB password", - "NoEcho": "true" - } - }, - "Resources" : { - "TowerTask": { - "Type": "AWS::ECS::TaskDefinition", - "Properties": { - "NetworkMode": "bridge", - "ContainerDefinitions": [ - { - "Name": "redis", - "Image": "cr.seqera.io/public/redis:7.0.10", - "Memory": 2000, - "Cpu": 0, - "PortMappings": [{ - "ContainerPort": 6379, - "HostPort": 6379 - }], - "Command": ["--appendonly yes"] - }, - { - "Name": "cron", - "Image": "cr.seqera.io/private/nf-tower-enterprise/backend:v25.3.0", - "Memory": 2000, - "Cpu": 0, - "Links": [ - "redis" - ], - "DependsOn": [ - { - "ContainerName": "redis", - "Condition": "START" - } - ], - "WorkingDirectory": "/work", - "EntryPoint": [ "/bin/sh" ], - "Command": [ "-c", "/migrate-db.sh; /tower.sh" ], - "Environment": [ - { - "Name": "TOWER_CONTACT_EMAIL", - "Value": { - "Ref": "TowerContactEmail" - } - }, - { - "Name": "TOWER_SMTP_HOST", - "Value": { - "Ref": "TowerSmtpHost" - } - }, - { - "Name": "TOWER_SMTP_PORT", - "Value": { - "Ref": "TowerSmtpPort" - } - }, - { - "Name": "TOWER_SMTP_USER", - "Value": { - "Ref": "TowerSmtpUser" - } - }, - { - "Name": "TOWER_SMTP_PASSWORD", - "Value": { - "Ref": "TowerSmtpPassword" - } - }, - { - "Name": "TOWER_DB_URL", - "Value": { - "Ref": "TowerDbUrl" - } - }, - { - "Name": "TOWER_DB_DRIVER", - "Value": "org.mariadb.jdbc.Driver" - }, - { - "Name": "TOWER_DB_DIALECT", - "Value": "io.seqera.util.MySQL55DialectCollateBin" - }, - { - "Name": "TOWER_DB_USER", - "Value": { - "Ref": "TowerDbUser" - } - }, - { - "Name": "TOWER_DB_PASSWORD", - "Value": { - "Ref": "TowerDbPassword" - } - }, - { - "Name": "TOWER_SERVER_URL", - "Value": { - "Ref": "TowerServerUrl" - } - }, - { - "Name": "MICRONAUT_ENVIRONMENTS", - "Value": "prod,redis,cron" - }, - { - "Name": "TOWER_ENABLE_PLATFORMS", - "Value": "awsbatch-platform,azbatch-platform,gls-platform,slurm-platform" - }, - { - "Name": "TOWER_JWT_SECRET", - "Value": { - "Ref": "TowerJwtSecret" - } - }, - { - "Name": "TOWER_CRYPTO_SECRETKEY", - "Value": { - "Ref": "TowerCryptoSecretkey" - } - }, - { - "Name": "TOWER_LICENSE", - "Value": { - "Ref": "TowerLicense" - } - }, - { - "Name": "FLYWAY_LOCATIONS", - "Value": "classpath:db-schema/mysql" - } - ] - }, - { - "Name": "frontend", - "Image": "cr.seqera.io/private/nf-tower-enterprise/frontend:v25.3.0", - "Memory": 2000, - "Cpu": 0, - "Essential": false, - "PortMappings": [{ - "ContainerPort": 80, - "HostPort": 80 - }], - "Links": [ - "backend" - ], - "DependsOn": [ - { - "ContainerName": "backend", - "Condition": "START" - } - ] - }, - { - "Name": "backend", - "Hostname": "backend", - "Memory": 2000, - "Cpu": 0, - "Image": "cr.seqera.io/private/nf-tower-enterprise/backend:v25.3.0", - "PortMappings": [{ - "ContainerPort": 8080, - "HostPort": 8080 - }], - "Essential": false, - "Links": [ - "redis", - "cron" - ], - "WorkingDirectory": "/work", - "DependsOn": [ - { - "ContainerName": "cron", - "Condition": "START" - }, - { - "ContainerName": "redis", - "Condition": "START" - } - ], - "Environment": [ - { - "Name": "TOWER_CONTACT_EMAIL", - "Value": { - "Ref": "TowerContactEmail" - } - }, - { - "Name": "TOWER_SMTP_HOST", - "Value": { - "Ref": "TowerSmtpHost" - } - }, - { - "Name": "TOWER_SMTP_PORT", - "Value": { - "Ref": "TowerSmtpPort" - } - }, - { - "Name": "TOWER_SMTP_USER", - "Value": { - "Ref": "TowerSmtpUser" - } - }, - { - "Name": "TOWER_SMTP_PASSWORD", - "Value": { - "Ref": "TowerSmtpPassword" - } - }, - { - "Name": "TOWER_DB_URL", - "Value": { - "Ref": "TowerDbUrl" - } - }, - { - "Name": "TOWER_DB_DRIVER", - "Value": "org.mariadb.jdbc.Driver" - }, - { - "Name": "TOWER_DB_DIALECT", - "Value": "io.seqera.util.MySQL55DialectCollateBin" - }, - { - "Name": "TOWER_DB_USER", - "Value": { - "Ref": "TowerDbUser" - } - }, - { - "Name": "TOWER_DB_PASSWORD", - "Value": { - "Ref": "TowerDbPassword" - } - }, - { - "Name": "TOWER_SERVER_URL", - "Value": { - "Ref": "TowerServerUrl" - } - }, - { - "Name": "MICRONAUT_ENVIRONMENTS", - "Value": "prod,redis,ha" - }, - { - "Name": "TOWER_ENABLE_PLATFORMS", - "Value": "awsbatch-platform,azbatch-platform,gls-platform,slurm-platform" - }, - { - "Name": "TOWER_JWT_SECRET", - "Value": { - "Ref": "TowerJwtSecret" - } - }, - { - "Name": "TOWER_CRYPTO_SECRETKEY", - "Value": { - "Ref": "TowerCryptoSecretkey" - } - }, - { - "Name": "TOWER_LICENSE", - "Value": { - "Ref": "TowerLicense" - } - }, - { - "Name": "FLYWAY_LOCATIONS", - "Value": "classpath:db-schema/mysql" - } - ], - "EntryPoint": [ "/bin/sh" ], - "Command": [ "-c", "/tower.sh" ] - }] - } - }, - "TowerService": { - "Type" : "AWS::ECS::Service", - "Properties" : { - "Cluster": { - "Ref": "ClusterName" - }, - "DesiredCount" : 1, - "ServiceName" : "TowerService", - "TaskDefinition": { - "Ref": "TowerTask" - }, - "LaunchType": "EC2" - } - } - } -} diff --git a/platform-enterprise_docs/enterprise/_templates/cloudformation/params.json.template b/platform-enterprise_docs/enterprise/_templates/cloudformation/params.json.template deleted file mode 100644 index 1e69ec983..000000000 --- a/platform-enterprise_docs/enterprise/_templates/cloudformation/params.json.template +++ /dev/null @@ -1,54 +0,0 @@ -[ - { - "ParameterKey": "ClusterName", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerSmtpUser", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerSmtpPassword", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerContactEmail", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerServerUrl", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerJwtSecret", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerCryptoSecretkey", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerLicense", - "ParameterValue": "" - }, - { - "ParameterKey": "TowerDbUrl", - "ParameterValue": "tower" - }, - { - "ParameterKey": "TowerDbUser", - "ParameterValue": "tower" - }, - { - "ParameterKey": "TowerDbPassword", - "ParameterValue": "tower" - }, - { - "ParameterKey": "TowerSmtpHost", - "ParameterValue": "email-smtp.eu-west-1.amazonaws.com" - }, - { - "ParameterKey": "TowerSmtpPort", - "ParameterValue": "587" - }, -] diff --git a/platform-enterprise_docs/enterprise/_templates/k8s/dbconsole.yml b/platform-enterprise_docs/enterprise/_templates/k8s/dbconsole.yml deleted file mode 100644 index 8828e7f20..000000000 --- a/platform-enterprise_docs/enterprise/_templates/k8s/dbconsole.yml +++ /dev/null @@ -1,34 +0,0 @@ -apiVersion: apps/v1 -kind: Deployment -metadata: - name: dbconsole - labels: - app: dbconsole -spec: - selector: - matchLabels: - app: dbconsole - template: - metadata: - labels: - app: dbconsole - spec: - containers: - - image: adminer:4.7.7 - name: dbconsole - ports: - - containerPort: 8080 - restartPolicy: Always ---- -apiVersion: v1 -kind: Service -metadata: - name: dbconsole -spec: - ports: - - port: 8080 - targetPort: 8080 - protocol: TCP - type: NodePort - selector: - app: dbconsole diff --git a/platform-enterprise_docs/enterprise/advanced-topics/cloudformation.md b/platform-enterprise_docs/enterprise/advanced-topics/cloudformation.md deleted file mode 100644 index 42c1d679e..000000000 --- a/platform-enterprise_docs/enterprise/advanced-topics/cloudformation.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "CloudFormation deployment (deprecated)" -description: Deploy Tower to ECS using CloudFormation -date: "12 Apr 2023" -tags: [ecs, cloudformation, deployment] ---- - -!!! danger "Deprecated" -This deployment option is deprecated, and will be removed in the future. We strongly recommend against using this option unless you're sufficiently experienced with CloudFormation to customize this template for your own infrastructure. - -Tower can be deployed via AWS CloudFormation, using the included configuration. - -This guide assumes that all [prerequisites](../prerequisites/aws) have been met. - -## Set up an ECS cluster - -1. Navigate to the ECS console in AWS. - -2. Select **Create cluster**. - -3. Select **Amazon ECS > Clusters > EC2 Linux + Networking**. - -### ECS Cluster Configuration - -- Name: _nf-tower_ - -**Instance Configuration** - -- Provisioning Model: On-Demand -- EC2 instance type: c4.2xlarge -- Number of instances: 1 -- EC2 AMI ID: Amazon Linux 2 -- Root EBS Volume Size (GiB): none -- Key pair: none - -### Networking Configuration - -- Create a new VPC - -**Container instance IAM role** - -- Create a new role (if the `ecsInstance` role doesn't exist) - -**Instance `ServerURL`** - -- Record the public IP of the instance in the ECS cluster e.g., `3.122.246.202` - -## Deploy Tower - -1. Download [aws-ecs-cloudformation.json](../_templates/cloudformation/aws-ecs-cloudformation.json) and [params.json.template](../_templates/cloudformation/params.json.template). - -2. Rename `params.template.json` to `params.json` and configure for your environment. - - For more information on configuration, visit the [Configuration](../configuration/overview) section. - -3. Deploy the Tower stack to your ECS cluster: - - ```bash - aws cloudformation create-stack \ - --stack-name Tower \ - --template-body file://aws-ecs-cloudformation.json \ - --parameters file://params.json - ``` - -You can delete the stack at any time, to uninstall Tower or update any parameters: - -```bash -aws cloudformation delete-stack \ - --stack-name Tower -``` diff --git a/platform-enterprise_docs/enterprise/configuration/mirroring.md b/platform-enterprise_docs/enterprise/configuration/mirroring.md new file mode 100644 index 000000000..edb3a7341 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/mirroring.md @@ -0,0 +1,44 @@ +--- +title: "Mirroring container images" +description: Mirror Seqera container images to your own registry +date: "12 Apr 2023" +tags: [containers, registry, configuration] +--- + +Mirroring Seqera container images to your own registry is recommended for production deployments. This ensures your deployments are not impacted by external registry availability and supports air-gapped environments. + +## Registry-native replication + +Use your container registry's built-in replication features to automatically sync images from `cr.seqera.io`: + +- [Amazon ECR replication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/replication.html) +- [Azure ACR artifact caching](https://learn.microsoft.com/en-us/azure/container-registry/artifact-cache-overview) +- [Harbor replication](https://goharbor.io/docs/latest/administration/configuring-replication/) + +## Skopeo + +Use [Skopeo](https://github.com/containers/skopeo) (v1.15+) when your registry doesn't support native replication. + +Authenticate with the Seqera registry: + +```bash +skopeo login --username 'robot$private+YOUR_ROBOT_USERNAME' -p 'YOUR_PASSWORD' cr.seqera.io +``` + +Create a YAML file (`seqera-images.yaml`) to specify which images to sync: + +```yaml +cr.seqera.io: + images-by-semver: + private/nf-tower-enterprise/backend: ">= v25.2.0" + private/nf-tower-enterprise/frontend: ">= v25.2.0" + private/nf-tower-enterprise/migrate-db: ">= v25.2.0" +``` + +Run the sync: + +```bash +skopeo sync --scoped --src yaml --dest docker seqera-images.yaml YOUR_REGISTRY +``` + +Schedule periodic sync jobs to keep images current. See the [Skopeo sync documentation](https://github.com/containers/skopeo/blob/main/docs/skopeo-sync.1.md) for advanced usage. diff --git a/platform-enterprise_docs/enterprise/configuration/wave.md b/platform-enterprise_docs/enterprise/configuration/wave.md index 50e810a27..f894fde92 100644 --- a/platform-enterprise_docs/enterprise/configuration/wave.md +++ b/platform-enterprise_docs/enterprise/configuration/wave.md @@ -5,34 +5,88 @@ date: "12 Apr 2023" tags: [wave, containers, configuration] --- -From version 22.4, Seqera Platform Enterprise supports the Seqera Wave containers service for on-prem installations. +Wave is Seqera's container provisioning service that enables on-demand container image management for Nextflow pipelines. Wave can provision containers dynamically during pipeline execution, removing the need to manually build and upload images to a container registry. -To learn more about Wave, see [Wave containers](https://wave.seqera.io). To learn more about Wave and Nextflow integration, see the [Nextflow documentation](https://www.nextflow.io/docs/latest/wave.html). +## Deployment options -## Pair your Seqera instance with Wave +Wave can be integrated with Seqera Platform in two ways: -To pair Seqera Enterprise with Wave, you need the following: +- **Seqera Wave service**: Use the hosted Wave service at `https://wave.seqera.io` (default for Seqera Cloud) +- **Self-hosted Wave**: Deploy Wave in your own infrastructure for full control over container builds and caching -- Credentials to authenticate to your (private or public) container registry configured in the Seqera UI. See the [container registry credentials](../../credentials/overview) instructions for your provider. +## Requirements -- Your container registry must allow ingress from the Wave service (`https://wave.seqera.io`). +### Network connectivity -- The Wave service (`https://wave.seqera.io`) must be accessible from the network where your Seqera instance is installed (i.e., the domain should be whitelisted in protected Seqera installations). +| Source | Destination | Purpose | +| :----- | :---------- | :------ | +| Seqera Platform | Wave server | API communication | +| Container registry | Wave server | Allow ingress for container operations | +| Compute environments | Wave server | Container image access during pipeline execution | -- The `TOWER_ENABLE_WAVE=true` and `WAVE_SERVER_URL="https://wave.seqera.io"` environment variables must be added to your Seqera configuration environment. +### Container registry credentials -:::note -Wave does not currently support container repositories that have private CA SSL certificates applied. -::: +Container registry credentials must be configured in the Seqera UI to authenticate with your private or public registries. See [container registry credentials](../../credentials/overview) for provider-specific instructions. -You can test connectivity with the Wave service by accessing https://wave.seqera.io/service-info, either from the browser or with cURL: +## Configuration -```curl -$ curl https://wave.seqera.io/service-info +### Connect to Seqera Wave service + +Configure Seqera Platform to use the hosted Wave service: + +| Variable | Description | +| :------- | :---------- | +| `TOWER_ENABLE_WAVE` | Set to `true` to enable Wave integration | +| `WAVE_SERVER_URL` | Wave server endpoint (default: `https://wave.seqera.io`) | + +### Connect to self-hosted Wave + +For self-hosted Wave deployments, set `WAVE_SERVER_URL` to your Wave server endpoint: + +| Variable | Description | +| :------- | :---------- | +| `TOWER_ENABLE_WAVE` | Set to `true` to enable Wave integration | +| `WAVE_SERVER_URL` | Your self-hosted Wave server URL (e.g., `https://wave.your-domain.com`) | + +### Verify connectivity + +Test connectivity to your Wave server: + +```bash +curl https://wave.seqera.io/service-info ``` -When these conditions are met, the Wave feature is available on the Seqera compute environment creation page (currently only available for AWS compute environments). +Replace `wave.seqera.io` with your self-hosted Wave endpoint if applicable. + +## Features enabled by Wave + +After Wave is enabled, the following features become available: + +- **Private container registries**: Access containers from private repositories using credentials stored in Seqera +- **Fusion file system**: High-performance cloud-native file system for pipeline execution +- **Container augmentation**: Dynamically extend existing containers with additional layers +- **Conda-based containers**: Provision containers from Conda or Bioconda packages on demand +- **Singularity support**: Build and provision Singularity/Apptainer format containers +- **Security scanning**: Automatic vulnerability scanning of built container images + +Wave features are available on the compute environment creation page after integration is configured. + +## Limitations + +- Wave does not support container repositories with private CA SSL certificates + +## Self-hosted Wave deployment + +For enterprises requiring full control over container builds, caching, and security scanning, Wave can be deployed in your own infrastructure. + +Self-hosted Wave supports: +- **Wave Lite**: Container augmentation and inspection capabilities (AWS, Azure, GCP) +- **Full Wave**: Complete build capabilities including Conda-based containers and security scanning (requires AWS EKS with EFS storage) + +See the [Wave documentation](https://docs.seqera.io/wave) for installation and configuration guidance. -After Wave is enabled, you can use private container repositories and the Fusion file system in your Nextflow pipelines. +## Additional resources -Wave can also be enabled in the Nextflow pipeline config file. See the [Nextflow documentation](https://www.nextflow.io/docs/latest/wave.html) for more information. +- [Wave documentation](https://docs.seqera.io/wave) +- [Nextflow Wave integration](https://www.nextflow.io/docs/latest/wave.html) +- [Seqera Containers](https://seqera.io/containers/) - Free community container registry diff --git a/platform-enterprise_docs/enterprise/docker-compose.md b/platform-enterprise_docs/enterprise/docker-compose.md index b9c1a5836..d6fcd09a3 100644 --- a/platform-enterprise_docs/enterprise/docker-compose.md +++ b/platform-enterprise_docs/enterprise/docker-compose.md @@ -5,13 +5,32 @@ date: "12 Feb 2024" tags: [docker, compose, deployment] --- -This guide assumes that all prerequisites have been met. Visit the corresponding **Prerequisites** page for your infrastructure provider. +Docker Compose deployments are suitable for evaluation, development, and small production workloads. -Seqera recommends configuring your database or Redis details in either `tower.yml` or `docker-compose.yml`, but not both. +## Prerequisites -:::note -The DB or Redis volume is persistent after a Docker restart by default. Use the `volumes` key in the `db` or `redis` section of your `docker-compose.yml` file to specify a local path to the DB or Redis instance. For your database or Redis volume to be ephemeral, remove the `volumes` key altogether. -::: +Before you begin, you need: +- Docker Engine and Docker Compose +- A MySQL 8 database +- A Redis 7 instance + +## Container images + +Seqera Enterprise container images are hosted on a private registry (`cr.seqera.io`). Access is provided as part of your purchase. Contact [support](https://support.seqera.io) if you require access. + +We recommend mirroring these images to your own private container registry for production use. See [Mirroring container images](./configuration/mirroring) for details. + +## Database configuration + +Create a MySQL database and user for Seqera: + +```sql +CREATE DATABASE tower; +CREATE USER 'tower'@'%' IDENTIFIED BY 'your_secure_password'; +GRANT ALL PRIVILEGES ON tower.* TO 'tower'@'%'; +``` + +See [Database configuration](./configuration/overview#seqera-and-redis-databases) for details. ## Deploy Seqera Enterprise diff --git a/platform-enterprise_docs/enterprise/helm.md b/platform-enterprise_docs/enterprise/helm.md index 6ec438f8c..21f388e90 100644 --- a/platform-enterprise_docs/enterprise/helm.md +++ b/platform-enterprise_docs/enterprise/helm.md @@ -9,10 +9,11 @@ tags: [helm, deployment, installation, kubernetes] ## Prerequisites -This guide assumes that all [Seqera prerequisites](./prerequisites/common) have been met. On top of the general requirements, ensure you have the following: - -- A Kubernetes cluster running a supported version. -- [Helm v3](https://helm.sh/docs/intro/install) and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed on your local machine. +Before you begin, you need: +- A Kubernetes cluster +- A MySQL 8 database +- A Redis 7 instance +- [Helm v3](https://helm.sh/docs/intro/install) and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally ## Installing the Helm chart diff --git a/platform-enterprise_docs/enterprise/kubernetes.md b/platform-enterprise_docs/enterprise/kubernetes.md index ff19d6370..b2b4b0e04 100644 --- a/platform-enterprise_docs/enterprise/kubernetes.md +++ b/platform-enterprise_docs/enterprise/kubernetes.md @@ -5,58 +5,64 @@ date: "21 Apr 2023" tags: [kubernetes, deployment] --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +Kubernetes deployments are recommended for production workloads requiring high availability and scalability. -This guide assumes that all prerequisites have been met. Visit the corresponding **Prerequisites** page for your infrastructure provider. +## Prerequisites -Complete the following procedures to install Seqera Platform Enterprise on a Kubernetes cluster: +Before you begin, you need: +- A Kubernetes cluster +- A MySQL 8 database +- A Redis 7 instance -### Create a namespace +### Recommended resources -Create a namespace to isolate Kubernetes resources used by Seqera Platform from the other resources on your cluster. +| Component | CPU | Memory | +| :-------- | :-- | :----- | +| Backend pod | 1 core | 1200 Mi request, 4200 Mi limit | -:::note -This installation guide assumes the use of `seqera-platform` as the installation namespace. Consider using a different one that better fits your cluster naming convention. -::: +## Container images -Create a namespace for the Seqera resources: +Seqera Enterprise container images are hosted on a private registry (`cr.seqera.io`). Access is provided as part of your purchase. Contact [support](https://support.seqera.io) if you require access. - ```bash - kubectl create namespace seqera-platform - ``` +We recommend mirroring these images to your own private container registry for production use. See [Mirroring container images](./configuration/mirroring) for details. -Switch to the namespace: +For development and proof of concept installations, you can use [image pull secrets](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) to pull directly from the Seqera registry. - ```bash - kubectl config set-context --current --namespace=seqera-platform - ``` +## Database configuration -### Configure container registry credentials +Create a MySQL database and user for Seqera: -Seqera Enterprise is distributed as a collection of Docker containers available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Contact [support](https://support.seqera.io) to get your container access credentials. After you've received your credentials, grant your cluster access to the registry: +```sql +CREATE DATABASE tower; +CREATE USER 'tower'@'%' IDENTIFIED BY 'your_secure_password'; +GRANT ALL PRIVILEGES ON tower.* TO 'tower'@'%'; +``` -1. Retrieve the `name` and `secret` values from the JSON file that you received from Seqera support. +See [Database configuration](./configuration/overview#seqera-and-redis-databases) for details. -1. Create a [secret][kubectl-secret]: +## Redis configuration - ```bash - kubectl create secret docker-registry cr.seqera.io \ - --docker-server=cr.seqera.io \ - --docker-username='' \ - --docker-password='' - ``` +Configure the Redis connection URL in your Seqera environment: - The credential `name` contains a dollar `$` character. Wrap the name in single quotes to prevent the Linux shell from interpreting this value as an environment variable. +```bash +TOWER_REDIS_URL=redis://:6379 +``` -1. Configure the Seqera cron service and the application frontend and backend to use the secret created in the previous step (see [tower-cron.yml](./_templates/k8s/tower-cron.yml) and [tower-svc.yml](./_templates/k8s/tower-svc.yml)): +Use a managed Redis service for production: +- [Amazon ElastiCache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) (`cache.m4.large` or larger) +- [Azure Cache for Redis](https://learn.microsoft.com/en-gb/azure/azure-cache-for-redis/cache-overview) (C3 tier or larger) +- [Google Memorystore](https://cloud.google.com/memorystore/docs/redis) (M2 tier or larger) - ```yaml - imagePullSecrets: - - name: "cr.seqera.io" - ``` +## Deploy Seqera Enterprise + +### Create a namespace + +Create a namespace for Seqera resources: - This parameter is already included in the templates linked above. If you use a name other than `cr.seqera.io` for the secret, update this value accordingly in the configuration files. +```bash +kubectl create namespace seqera-platform +kubectl config set-context --current --namespace=seqera-platform +``` ### Seqera ConfigMap @@ -72,70 +78,6 @@ Deploy the ConfigMap to your cluster after it is configured: The `configmap.yml` manifest includes both the `tower.env` and `tower.yml` files. These files are made available to the other containers through volume mounts. ::: -### Redis - -Seqera Enterprise requires a Redis database for caching purposes. Configure Redis manually by deploying a manifest to your cluster, or configure a managed Redis service. - -#### Deploy a Redis manifest to your cluster - -1. Download the appropriate manifest for your infrastructure: - - - [Amazon EKS](_templates/k8s/redis.eks.yml) - - [Azure AKS](_templates/k8s/redis.aks.yml) - - [Google Kubernetes Engine](_templates/k8s/redis.gke.yml) - -1. Deploy to your cluster: - - ```bash - kubectl apply -f redis.*.yml - ``` - -1. To run the Redis service as a container as part of your Docker or Kubernetes installation, specify the service name as part of the `TOWER_REDIS_URL`: - - ```bash - TOWER_REDIS_URL=redis://redis:6379 - ``` - -#### Managed Redis services - -Seqera supports managed Redis services such as [Amazon ElastiCache][aws-elasticache], [Azure Cache for Redis][azure-cache], or [Google Memorystore][memorystore]. - - - - -- Use a single-node cluster, as multi-node clusters are not supported -- Use an instance with at least 6GB capacity ([cache.m4.large][aws-cache-instances] or greater) -- Specify your private ElastiCache instance in the Seqera [environment variables](./configuration/overview.mdx#database-and-redis-manual-configuration): - - ```bash - TOWER_REDIS_URL=redis://:6379 - ``` - - - - -- Use a single-node cluster, as multi-node clusters are not supported -- Use an instance with at least 6 GB capacity ([C3][azure-cache-instances] or greater) -- Specify your private Azure Cache for Redis instance in the Seqera [environment variables](./configuration/overview.mdx#database-and-redis-manual-configuration): - - ```bash - TOWER_REDIS_URL=redis://:6379 - ``` - - - - -- Use a single-node cluster, as multi-node clusters are not supported -- Use an instance with at least 6 GB capacity ([M2][google-cache-instances] or greater) -- Specify your private Memorystore instance in the Seqera [environment variables](./configuration/overview.mdx#database-and-redis-manual-configuration): - - ```bash - TOWER_REDIS_URL=redis://:6379 - ``` - - - - ### Seqera cron service Download the [cron service manifest](_templates/k8s/tower-cron.yml) file. @@ -156,9 +98,9 @@ Download the [manifest](_templates/k8s/tower-svc.yml). To deploy the manifest to your cluster, run the following: - ```bash - kubectl apply -f tower-svc.yml - ``` +```bash +kubectl apply -f tower-svc.yml +``` #### Seqera frontend unprivileged @@ -258,24 +200,6 @@ The initContainers will wait until both the Seqera and pipeline optimization ser Studios is available from Seqera Platform v24.1. If you experience any problems during the deployment process [contact Seqera support](https://support.seqera.io). Studios in Enterprise is not installed by default. ::: -### Database console - -Use the [dbconsole.yml](_templates/k8s/dbconsole.yml) manifest to deploy a simple web frontend to the Seqera database. Though not required, this can be useful for administrative purposes. - -1. Deploy the database console: - - ```bash - kubectl apply -f dbconsole.yml - ``` - -1. Enable a port-forward for the database console to your local machine: - - ```bash - kubectl port-forward deployment/dbconsole 8080:8080 - ``` - -1. Access the database console in a web browser at `http://localhost:8080`. - ### High availability To configure Seqera Enterprise for high availability, note that: @@ -285,16 +209,9 @@ To configure Seqera Enterprise for high availability, note that: - The `cron` service may only have a single instance - The `groundswell` service may only have a single instance -[aws-cache-instances]: https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/CacheNodes.SupportedTypes.html [aws-configure-ingress]: https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.2/guide/ingress/annotations/ -[aws-elasticache]: https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html -[azure-cache]: https://learn.microsoft.com/en-gb/azure/azure-cache-for-redis/cache-overview -[azure-cache-instances]: https://azure.microsoft.com/en-gb/pricing/details/cache/ [azure-configure-ingress]: https://docs.microsoft.com/en-us/azure/application-gateway/ingress-controller-annotations -[google-cache-instances]: https://cloud.google.com/memorystore/docs/redis/pricing#instance_pricing [google-configure-ingress]: https://cloud.google.com/kubernetes-engine/docs/concepts/ingress [k8s-ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ [k8s-load-balancer]: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer [k8s-node-port]: https://kubernetes.io/docs/concepts/services-networking/service/#nodeport -[kubectl-secret]: https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kubectl/ -[memorystore]: https://cloud.google.com/memorystore/docs/redis diff --git a/platform-enterprise_docs/enterprise/overview.md b/platform-enterprise_docs/enterprise/overview.md index 36980b8ee..cbe9dfd34 100644 --- a/platform-enterprise_docs/enterprise/overview.md +++ b/platform-enterprise_docs/enterprise/overview.md @@ -62,7 +62,7 @@ _Reference architecture diagram of Seqera Platform Enterprise on AWS using Elast ## Application container images -Seqera Enterprise is distributed as a collection of Docker containers available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Contact [support](https://support.seqera.io) to get your container access credentials. Follow [these instructions](./prerequisites/common.md) to learn how to authenticate and pull the Seqera container images, and replicate them to your own registry. +Seqera Enterprise is distributed as a collection of Docker containers available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Contact [support](https://support.seqera.io) to get your container access credentials. ## Support diff --git a/platform-enterprise_docs/enterprise/prerequisites/aws.md b/platform-enterprise_docs/enterprise/prerequisites/aws.md deleted file mode 100644 index 63fbd0163..000000000 --- a/platform-enterprise_docs/enterprise/prerequisites/aws.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: "AWS" -description: Prerequisites for AWS deployments -date: "12 Apr 2023" -tags: [aws, prerequisites, configuration, ec2, ses, rds] ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -This page describes the infrastructure and other prerequisites for deploying Seqera Platform Enterprise on Amazon Web Services (AWS). - -Run the Seqera container with [Docker](../docker-compose) on an AWS EC2 instance, or with [Kubernetes](../kubernetes) on an Amazon EKS cluster. You must satisfy the requirements for your installation target: - -- **SMTP server**: If you don't have an email server, use [Amazon Simple Email Service](https://aws.amazon.com/ses/). - - :::note - Amazon [blocks EC2 traffic over port 25 by default](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/). Your integration must use a port that can successfully reach your SMTP server. - ::: - -- **MySQL database**: An external database, such as one provided by [Amazon Relational Database Service](https://aws.amazon.com/rds/), is highly recommended for production deployments. - -- **Redis-compatible cache**: An external Redis-compatible cache, such as one provided by [Amazon ElastiCache](https://aws.amazon.com/elasticache/), is highly recommended for production deployments. - -- **(Optional) SSL certificate**: HTTP must not be used in production environments. An SSL certificate is required for your Seqera instance to handle HTTPS traffic. See [SSL/TLS configuration](../configuration/ssl_tls#aws-deployments-manage-ssl-certificates-with-amazon-certificate-manager-acm) for more information. - - :::note - HTTP-only implementations **must** set the `TOWER_ENABLE_UNSAFE_MODE=true` environment variable in the Seqera hosting infrastructure to enable user login. HTTP must not be used in production environments. - ::: - -- **(Optional) AWS Parameter Store**: Store sensitive Seqera configuration values as SecureString [AWS Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) parameters. See [AWS Parameter Store configuration](../configuration/aws_parameter_store) for instructions. This is recommended for production environments. - -- **(Optional) DNS**: DNS is required to support human-readable domain names and load-balanced traffic. If you don't have access to a pre-existing DNS service, use [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html). - -### Prerequisites for Docker - -An [EC2](https://aws.amazon.com/ec2/) instance is required. See [Amazon EC2](#amazon-ec2) for instructions to provision an EC2 instance for this purpose. - -### Prerequisites for EKS - -If you're installing Seqera Enterprise with Kubernetes, an [Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) cluster is required. See the [EKS documentation](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html) to provision your own cluster. - -
- EKS cluster requirements - - - Kubernetes 1.19 or later - - - **Subnet requirements** - - - At least 2 subnets across two different Availability Zones - - Subnets must be tagged for [AWS Load Balancer Controller auto-discovery](https://docs.aws.amazon.com/eks/latest/userguide/network_reqs.html) - - Public subnets must be configured to [auto-assign IPs on launch](https://aws.amazon.com/blogs/containers/upcoming-changes-to-ip-assignment-for-eks-managed-node-groups/) - - Public and private subnets must allow egress traffic to the public internet - - - **RBAC requirements** - - - The cluster must be created by a non-root user - - `aws-auth` must be updated to [allow access to additional IAM users/roles](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) (if needed) - - - **Addons** - - - Install the [cert-manager](https://cert-manager.io/docs/) - - Install the [AWS Load Balancer Controller](https://docs.aws.amazon.com/eks/latest/userguide/aws-load-balancer-controller.html) - - - **Ingress** - - - ALB provisioning via the [AWS Load Balancer Controller](https://docs.aws.amazon.com/eks/latest/userguide/aws-load-balancer-controller.html) - - ALB integration with the [Amazon Certificate Manager](https://aws.amazon.com/certificate-manager/) - - Additionally, the ingress assumes the presence of SSL certificates, DNS resolution, and ALB logging. If you've chosen not to use some or all of these features, you'll need to modify the manifest accordingly before applying it to the cluster. - -
- -## AWS setup - -Set up commonly-used AWS services for Seqera deployment. - -### Fetch Seqera config values from AWS Parameter Store - -From version 23.1, you can retrieve Seqera Enterprise configuration values remotely from the AWS Parameter Store. See [AWS Parameter Store configuration](../configuration/aws_parameter_store) for instructions. - -### Amazon SES - -Seqera Enterprise supports AWS Simple Email Service (SES) as an alternative to traditional SMTP servers for sending application emails. - -:::caution -If you use AWS SES in sandbox mode, both the _sender_ and the _receiver_ email addresses must be verified via AWS SES. Sandbox is not recommended for production use. See the [AWS docs](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) for instructions to move out of the sandbox. -::: - -- See [Obtaining SES SMTP credentials using the SES console](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html#smtp-credentials-console) for instructions to set up SES to send emails from your preferred address. - -- To prevent emails from SES being flagged as spam, see these AWS instructions for setting up an email authentication method: - - - [DKIM for a domain](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-authentication-dkim-easy-setup-domain.html) - - - [SPF authentication](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-authentication-spf.html) - -### Amazon RDS - -External databases for Seqera Enterprise deployments require: - -- A **MySQL8 Community** DB instance -- At least 2 vCPUs, 8 GB memory, and 30 GB SSD storage -- Manual MySQL user and database schema creation. See [Database configuration](../configuration/overview#seqera-and-redis-databases) for more details. - -:::caution -Recommended instance class and storage requirements depend on the number of parallel pipelines you expect to run. -::: - - - - -See [Creating an Amazon RDS DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html) to guide you through the external database setup for your production deployment. - - - - -To create a DB instance with the AWS CLI, call the [create-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html) command, replacing `INSTANCE_NAME`, `SECURITY_GROUP`, `DB_USER`, and `DB_PASSWORD` with your unique values: - -```bash -aws rds create-db-instance \ - --engine mysql \ - --db-instance-identifier INSTANCE_NAME \ - --allocated-storage 30 \ - --db-instance-class db.m5d.large \ - --vpc-security-group-ids SECURITY_GROUP \ - --db-subnet-group SUBNET_GROUP \ - --master-username DB_USER \ - --master-user-password DB_PASSWORD \ -``` - - - - -After your database is created: - -- Update the inbound rules for the underlying EC2 instance to allow MySQL connections. -- Update your Seqera [configuration](../configuration/overview#seqera-and-redis-databases) with the database hostname, username, and password. - -### Amazon EC2 - -See [Getting started with Amazon EC2](https://aws.amazon.com/ec2/getting-started/) for instructions to create your EC2 instance. - -Create an instance with these attributes: - -- **Amazon Machine Image (AMI)**: Amazon Linux 2023 Optimized -- **Instance type**: c5a.xlarge or c5.large with 4 CPUs and 8 GB RAM -- **Root storage**: 30 GB -- **Tags**: It is helpful to use a descriptive `Name` value for your instance, such as `seqera-app-server`. -- **Security Group name**: Seqera deployment manifests provided in this installation guide use `tower-sg` by default. If you choose to use a custom name, this must be updated consistently across your deployment files. -- **Keypair**: It is security best practice to use a **new** keypair for your production deployment instance. - -After your instance is launched: - -1. Use the key pair to connect to the server with SSH and its public IP address. Terminal-based SSH is easier to use than browser-based SSH for copying and pasting text. - -1. [Install Docker](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-docker.html#install-docker-instructions). - -1. [Install Docker Compose](https://docs.docker.com/compose/install/linux/#install-the-plugin-manually). - -1. Confirm that Docker Compose is installed: - - ```bash - docker compose version - ``` - -## Seqera container images - -Seqera Enterprise is distributed as a collection of container images available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Refer to the instructions in the [Common prerequisites](./common.md#vendoring-seqera-container-images-to-your-own-registry) page to replicate the required images to your internal container registry for High Availability or for air-gapped environments. - -## Next steps - -See [Configuration](../configuration/overview). - -[create-db-instance-cli]: https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html diff --git a/platform-enterprise_docs/enterprise/prerequisites/azure.md b/platform-enterprise_docs/enterprise/prerequisites/azure.md deleted file mode 100644 index 565227049..000000000 --- a/platform-enterprise_docs/enterprise/prerequisites/azure.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -title: "Azure" -description: Prerequisites for Azure deployments -date: "12 Apr 2023" -tags: [azure, prerequisites, configuration] ---- - -This page describes the infrastructure and other prerequisites for deploying Seqera Platform Enterprise on Microsoft Azure. - -Run the Seqera container images with [Docker](../docker-compose) on an Azure VM instance or with [Kubernetes](../kubernetes) on an Azure AKS cluster. You must satisfy the requirements for your installation target: - -- A resource group and a storage account are required to use Azure. See [Azure setup](#azure-setup) below to provision these resources. -- **SMTP server**: If you don't have an email server, see [Azure's recommended method of sending email][azure-sendmail]. Microsoft recommends [Microsoft 365][msft-365] or the third party service [SendGrid][sendgrid]. -- **MySQL database**: An external database such as [Azure Database for MySQL][azure-db-create-portal] is highly recommended for production deployments. -- **Redis-compatible cache**: An external Redis-compatible cache, such as [Azure Cache for Redis](https://azure.microsoft.com/en-gb/products/cache/), is highly recommended for production deployments. -- **SSL certificate**: An SSL certificate is required for your Seqera instance to handle HTTPS traffic. - - :::caution - HTTP-only implementations **must** set the `TOWER_ENABLE_UNSAFE_MODE=true` environment variable in the Seqera hosting infrastructure to enable user login. HTTP must not be used in production environments. - ::: - -- **DNS**: (Optional) DNS is required to support human-readable domain names and load-balanced traffic. See [Azure DNS][azure-dns] to learn about domain aquisition and record management. - -These decisions must be made before you continue as they impact how Seqera configuration files are updated. - -### Prerequisites for Docker - -A Linux VM instance is required to deploy Seqera Enterprise via Docker Compose. See the [detailed instructions](#azure-setup) to provision a VM instance for this purpose. - -### Prerequisites for AKS - -An [Azure Kubernetes Service (AKS)][aks-walkthrough] cluster is required to deploy Seqera Enterprise via Kubernetes. - -## Azure setup - -Set up commonly used Azure services for Seqera deployment. - -### Azure resource group - -Create a resource group: -- [Via the Azure portal][azure-rg-portal] -- [Via the Azure CLI][azure-rg-cli] - -
- Create a resource group via Azure portal - - 1. Sign in to the [Azure portal](https://portal.azure.com). - 1. Select **Resource groups**. - 1. Select **Add**. - 1. Enter the following values: - - **Subscription**: Select your Azure subscription. - - **Resource group**: Enter a new resource group name (such as `towerrg`). - - **Region**: Select the region where your assets will exist (such as `East US`). - 1. Select **Review and Create**. - 1. Select **Create**. - -
-
- Create a resource group via Azure CLI - - Run the `az group create` command: - - ```bash - az group create --name $MY_RESOURCE_GROUP_NAME --location $REGION - ``` - -
- -### Azure storage account - -Create a storage account: -- [Via the Azure portal][azure-storage-portal] -- [Via the Azure CLI][azure-storage-cli] - -
- Create a storage account via Azure portal - - 1. Sign in to the [Azure portal](https://portal.azure.com). - 1. Select **Storage accounts**. - 1. Select **Create**. - 1. Enter the following values: - - **Subscription**: Select your Azure subscription. - - **Resource group**: Enter your resource group name. - - **Storage account name**: Enter a new storage account name (such as `towerstorage`). - - **Region**: Select the region where your Resource Group exists (such as `East US`). - - **Performance**: Select `Standard`. - - **Redundancy**: Select `Geo-redundant storage (GRS)`. - 1. Select **Review + create**. The default values are used in the other tabs. See [Create a storage account][azure-storage-portal] for further details on each setting. - 1. Select **Create**. - -
-
- Create a storage account via Azure CLI - - Run the `az storage account create` command: - - ```bash - az storage account create -n towerstorage -g towerrg -l eastus --sku Standard_GRS - ``` - -
- -### Azure MySQL DB instance - -External databases for Seqera Enterprise deployments require: -- A **MySQL8 Community** DB instance. -- At least **2 vCPUs**, **8 GB memory**, and **30 GB** SSD storage. -- Manual MySQL user and database schema creation. See [Database configuration](../configuration/overview#seqera-and-redis-databases) for more details. - -:::caution -Recommended instance performance and storage requirements depend on the number of parallel pipelines you expect to run. -::: - -Create an Azure MySQL DB instance: -- [Via Azure portal][azure-db-create-portal] -- [Via Azure CLI][azure-db-create-cli] - -
- Create a MySQL DB instance via Azure portal - - 1. In the Azure portal, search for and select **Azure Database for MySQL servers**. - 1. Select **Create**. - 1. On the **Select Azure Database for MySQL deployment option** pane, select **Flexible server** as the deployment option. - 1. On the **Basics** tab, enter or select the following: - - Your **Subscription** name - - Your **Resource group** name - - A **Server name** such as `towerdbserver` - - Your **Region** - - The **Workload type**, based on your required `max_connections` - - **High availability** — high availability is recommended for production deployments - - **Standby availability zone** — standby server zone location - - **MySQL version** — 8.0 - - An **Admin username** to access the server - - A **Password** to access the server - - Your **Compute + storage** requirements, considering the minimum performance requirements outlined above - 1. Configure networking options. - 1. Select **Review + create**, then **Create**. - 1. Disable invisible primary keys, which can interfere with upgrades to newer releases of Seqera Platform Enterprise. Azure Database for MySQL creates invisible primary keys automatically by default. For more information, see [Steps to disable a GIPK][azure-gipk]. - -
-
- Create a MySQL DB instance via Azure CLI - - 1. Run `az mysql flexible-server create` to create your server: - - ```bash - az mysql flexible-server create --location eastus --resource-group towerrg --name towerdbserver --admin-user username --admin-password password --sku-name Standard_B2ms --tier Burstable --public-access 0.0.0.0 --storage-size 30 --version 8.0 --high-availability ZoneRedundant --zone 1 --standby-zone 3 --storage-auto-grow Enabled --iops 500 - ``` - - The `sku-name`, `tier`, `storage-size`, and `iops` values depend on your performance requirements. - - 1. Run `az mysql flexible-server db create` to create a database on your server: - - ```bash - az mysql flexible-server db create --resource-group towerrg - --server-name towerdbserver - --database-name towerdb - ``` - 1. Disable invisible primary keys, which can interfere with upgrades to newer releases of Seqera Platform Enterprise. Azure Database for MySQL creates invisible primary keys automatically by default. For more information, see [Steps to disable a GIPK][azure-gipk]. - -
- -After your database is created, update your Seqera [configuration](../configuration/overview#seqera-and-redis-databases) with the database hostname, Admin username, and password. - -:::note -When creating a MySQL user, use the `USER@HOSTNAME` format for the `TOWER_DB_USER` environment variable. For Azure managed MySQL, it's [recommended][azure-db-config] to pass an explicit `serverTimezone` to the `TOWER_DB_URL` environment variable, which (depending on your configuration) may be `UTC`. The DB connection string should be similar to `jdbc:mysql://towerdbserver.mysql.database.azure.com/towerdb?serverTimezone=UTC`. -::: - -### Azure Linux VM - -Create a VM instance with these attributes: - -- Use **default values** unless otherwise specified. -- At least **2 CPUS** and **8GB RAM**. -- **Ubuntu Server 22.04 LTS - Gen2** image. -- **Accessible by SSH**. - -Create an Azure Linux VM: -- [Via the Azure portal][azure-linux-vm-portal] -- [Via the Azure CLI][azure-linux-vm-cli] - -
- Create a VM via Azure portal - - 1. Under **Basics**, select your **Subscription** and **Resource group**. - 1. Under **Instance details**: - - Enter a **VM name** - - Select the same **Region** as your resource group. - - Select the **Ubuntu Server 24.04 LTS - Gen2** image. - - Do not set the VM as an **Azure Spot instance**. - - Select the **Size** — B2ps v2 or higher is recommended. - 1. Under **Administrator account**: - - Select **SSH public key** - - Enter a **username** - - Select **Generate new key pair** - - Enter a **Key pair name** - 1. Under **Inbound port rules**: - - Select **Allow selected ports** - - Select **SSH (22)**, **HTTP (8000)**, **HTTP (80)**, and **HTTPS (443)** (required for SSL termination in production environments) from the dropdown - 1. Select **Review + create** at the bottom of the page. - 1. Review your VM details, then select **Create**. - 1. When the **Generate new key pair** window opens, select **Download private key and create resource**. Your key file will be download as `myKey.pem`. Note the path to which it was downloaded. - 1. On the page for your new VM, copy the **Public IP address**. - - To make the VM's IP address static: - - 1. Enter **Public IP addresses** in the search. - 1. Under **Services**, select **Public IP addresses**. - 1. On the **Public IP addresses** page, select the entry containing your VM name. A page opens with that IP's details. - 1. Select **Configuration** from the left-hand navigation panel. - 1. Confirm that your IP address assignment is **Static**. - 1. Do not add a custom DNS name label to the VM. - - To allow ingress on port 8000: - - 1. Enter **Virtual Machines** in the search bar. - 1. Under **Services**, select **Virtual machines**. - 1. On the **Virtual machines** page, select your VM name to navigate to the VM details. - 1. Select **Networking** from the left-hand navigation panel. - 1. **Add inbound port rule** for port 8000. - - To allow ingress on port 443 (required for SSL/TLS termination in production environments): - - 1. Enter **Virtual Machines** in the search bar. - 1. Under **Services**, select **Virtual machines**. - 1. On the **Virtual machines** page, select your VM name to navigate to the VM details. - 1. Select **Networking** from the left-hand navigation panel. - 1. **Add inbound port rule** for port 443. - - Connect to the VM via SSH: - - 1. On a macOS or Linux machine, open a terminal and set read-only permission on the `myKey.pem` file with `chmod 400 ~/Downloads/myKey.pem`. - 1. Install Docker: - 1. [Install Docker using the apt repository][docker]. - 1. Confirm that Docker Compose is installed: - - ```bash - docker compose version - Docker Compose version v2.24.1 - ``` - -
-
- Create a VM via Azure CLI - - Run `az vm create`: - - ```bash - az vm create \ - --resource-group towerrg \ - --name towervm \ - --image Canonical:0001-com-ubuntu-minimal-jammy:minimal-22_04-lts-gen2:latest \ - --admin-username username \ - --assign-identity \ - --generate-ssh-keys \ - --public-ip-sku Standard - ``` - -
- -## Seqera container images - -Seqera Enterprise is distributed as a collection of container images available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Refer to the instructions in the [Common prerequisites](./common.md#vendoring-seqera-container-images-to-your-own-registry) page to replicate the required images to your internal container registry for High Availability or for air-gapped environments. - -## Next steps - -See [Configuration](../configuration/overview.mdx). - -[docker]: https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository -[aks-walkthrough]: https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal -[azure-db-create-cli]: https://learn.microsoft.com/en-us/azure/mysql/flexible-server/quickstart-create-server-cli -[azure-db-create-portal]: https://learn.microsoft.com/en-us/azure/mysql/flexible-server/quickstart-create-server-portal -[azure-db-config]: https://docs.microsoft.com/en-us/azure/mysql/connect-java#prepare-a-configuration-file-to-connect-to-azure-database-for-mysql -[azure-gipk]: https://learn.microsoft.com/en-us/azure/mysql/flexible-server/concepts-limitations#steps-to-disable-a-gipk -[azure-dns]: https://docs.microsoft.com/en-us/azure/dns/dns-overview -[azure-linux-vm-cli]: https://learn.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-cli#create-the-virtual-machine -[azure-linux-vm-portal]: https://learn.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-portal?tabs=ubuntu -[azure-rg-cli]: https://learn.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-cli#create-a-resource-group -[azure-rg-portal]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal -[azure-sendmail]: https://docs.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity#recommended-method-of-sending-email -[azure-storage-portal]: https://learn.microsoft.com/en-ca/azure/storage/common/storage-account-create?tabs=azure-portal#create-a-storage-account-1 -[azure-storage-cli]: https://learn.microsoft.com/en-us/cli/azure/storage/account?view=azure-cli-latest#az-storage-account-create -[msft-365]: https://docs.microsoft.com/en-us/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365 -[sendgrid]: https://docs.sendgrid.com/for-developers/partners/microsoft-azure-2021 diff --git a/platform-enterprise_docs/enterprise/prerequisites/common.md b/platform-enterprise_docs/enterprise/prerequisites/common.md deleted file mode 100644 index 3116fa19b..000000000 --- a/platform-enterprise_docs/enterprise/prerequisites/common.md +++ /dev/null @@ -1,107 +0,0 @@ -# Common prerequisites to all Enterprise installations - -Before installing Seqera Enterprise, ensure that the following prerequisites are met, as well as any additional prerequisites specified for your chosen infrastructure provider, such as [AWS](./aws), [GCP](./gcp), [Azure](./azure) or [on-premises installations](./on-prem). - -## Vendoring Seqera container images to your own registry - -Seqera Enterprise is distributed as a collection of container images available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Contact [support](https://support.seqera.io) to get your container access credentials. - -Vendoring images to your own container registry ensures that your deployments are not impacted by the potential unavailability of the Seqera container registry due to network issues, or to deploy Seqera in air-gapped environments. We recommend vendoring images to your own container registry, such as Amazon Elastic Container Registry (ECR), Google Container Registry (GCR), Docker Hub, among others. - -Three options are available to vendor images: -1. Automated replication using Container Registry native functionality (**recommended**): Use your container registry's native replication features to automatically replicate images from the Seqera container registry to your own registry. This option is only available if your container registry supports replication from external registries. -1. Automated replication using Skopeo: Use a tool like [Skopeo](https://github.com/containers/skopeo) to automate the process of copying container images between registries. -1. Manual replication: Pull images from the Seqera container registry, re-tag them, and push them to your preferred container registry. This process is described in detail below. - -### Automated replication using Container Registries - -Several container registries offer native replication features that can be used to automatically replicate images from external registries like the Seqera container registry `cr.seqera.io` to your own registry. This is the recommended approach as it simplifies the management of image replication and ensures that your registry stays up-to-date with the latest Seqera images. - -As a reference, here are links to the documentation for setting up replication in some popular container registries: -- [Amazon Elastic Container Registry (ECR) Replication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/replication.html) -- [Azure Container Registry (ACR) Artifact caching](https://learn.microsoft.com/en-us/azure/container-registry/artifact-cache-overview) -- [Harbor Replication](https://goharbor.io/docs/latest/administration/configuring-replication/) - -### Automated replication with Skopeo - -[Skopeo](https://github.com/containers/skopeo) is a command-line utility that performs various operations on container images and image repositories. It can sync external image repositories like the Seqera container registry `cr.seqera.io` to an internal registry. Refer to the Skopeo documentation for installation instructions. -If possible, always replicate images using your internal container registry native functionality as described in the previous section. Use Skopeo only if your container registry does not support replication from external registries. Note that Skopeo does not continuously monitor for new images, so you will need to set up a periodic job (for example, using a CI/CD pipeline) to keep your internal registry up-to-date with the latest Seqera images. -We recommend installing the latest version of Skopeo (or at least v1.15+ to work with the `images-by-semver` option in the `sync` command). - -1. Configure `skopeo` with the credentials to access the Seqera container registry, and your internal registry if needed. - - ```console - skopeo login --username 'robot$private+YOUR_ROBOT_USERNAME' -p 'YOUR_PASSWORD' cr.seqera.io - ``` - - Make sure to use single quotes around the username of the Seqera container registry robot account since it contains a dollar sign (`$`). - -1. Listing the available tags for a given image can be done with the `list-tags` command: - - ```console - skopeo list-tags docker://cr.seqera.io/private/nf-tower-enterprise - ``` - -1. Syncing images can be done with the `sync` command. For example, to sync all images stored in the `cr.seqera.io/private/nf-tower-enterprise/data-studio/connect-server` repository to your internal registry, run: - - ```console - skopeo sync --scoped --src docker --dest docker cr.seqera.io/private/nf-tower-enterprise/data-studio/connect-server YOUR_INTERNAL_REGISTRY - ``` - - Note that `--scoped` will populate your internal registry with images like `YOUR_INTERNAL_REGISTRY/cr.seqera.io/private/nf-tower-enterprise/data-studio/connect-server`. - More advanced usage examples are available in the Skopeo documentation: https://github.com/containers/skopeo/blob/main/docs/skopeo-sync.1.md#examples - -To avoid duplicating several years of Seqera images, we recommend using the `images-by-semver` option in the `sync` command. This option allows you to specify semantic versioning constraints for each image to be synced. For example, to sync all images with tags greater than or equal to a certain version, create a YAML file (for example, `seqera-container-registry.yaml`) with content similar to the following (adapt it to the versions you want to sync and the images you need): - -```yaml -cr.seqera.io: - images-by-semver: - private/nf-tower-enterprise/backend: ">= v25.2.0" - private/nf-tower-enterprise/frontend: ">= v25.2.0" - private/nf-tower-enterprise/migrate-db: ">= v25.2.0" - private/nf-tower-enterprise/data-studio/connect-server: ">= 0.8.0" - private/nf-tower-enterprise/data-studio/connect-proxy: ">= 0.8.0" - private/nf-tower-enterprise/wave: ">= v1.23.0" - private/nf-tower-enterprise/groundswell: ">= 0.4.0" -``` - -Note that some image tags are prefixed with `v` while others are not. -Then run the following command to sync all specified images to your internal registry: - -```console -skopeo sync --scoped --src yaml --dest docker seqera-container-registry.yaml YOUR_INTERNAL_REGISTRY -``` - -The above command can be automated with a scheduled job or a CI/CD pipeline to periodically update your internal registry with the latest Seqera images. - -An alternative to using Skopeo is to use [`gcrane`](https://docs.cloud.google.com/artifact-registry/docs/docker/copy-images), a tool from Google that can copy container images between registries. However, GCrane only supports copying one image at a time, so it may require more scripting to automate the replication of multiple images. - -### Manual replication - -The general process to manually replicate images involves: - -1. Login to the Seqera container registry, and your internal registry if needed (instructions for [AWS ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html), [GCP GCR](https://docs.cloud.google.com/artifact-registry/docs/docker/authentication), [Azure ACR](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-authentication?tabs=azure-cli)). - - ```console - docker login cr.seqera.io -u 'robot$private+YOUR_ROBOT_USERNAME' -p 'YOUR_PASSWORD' - ``` - - Make sure to use single quotes around the username of the Seqera container registry robot account since it contains a dollar sign (`$`). - -1. Downloading the image from the Seqera container registry. - - ```console - docker pull cr.seqera.io/private/nf-tower-enterprise/backend:v25.2.3 - ``` - -1. Re-tagging the image. - - ```console - docker tag cr.seqera.io/private/nf-tower-enterprise/backend:v25.2.3 YOUR_INTERNAL_REGISTRY/your-repo/backend:v25.2.3 - ``` - -1. Pushing the image to your preferred container registry (for example, ECR, GCR, Docker Hub). - - ```console - docker push YOUR_INTERNAL_REGISTRY/your-repo/backend:v25.2.3 - ``` diff --git a/platform-enterprise_docs/enterprise/prerequisites/gcp.md b/platform-enterprise_docs/enterprise/prerequisites/gcp.md deleted file mode 100644 index a2b3578fa..000000000 --- a/platform-enterprise_docs/enterprise/prerequisites/gcp.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: "Google Cloud" -description: Prerequisites for GCP deployments -date: "12 Apr 2023" -tags: [gcp, prerequisites, configuration] ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -This page describes the infrastructure and other prerequisites for deploying Seqera Platform Enterprise on Google Cloud Platform (GCP). - -Run the Seqera container with [Docker](../docker-compose) on a GCP VM instance or with [Kubernetes](../kubernetes) on a Google Kubernetes Engine cluster. You must satisfy the requirements for your installation target: - -- **SMTP server**: If you don't have an email server, Google Cloud provides several ways to send emails, such as [SendGrid][sendgrid], [Mailgun][mailgun], and [Mailjet][mailjet]. Work with your IT team to select the best solution for your organization. -- **MySQL database**: An external database such as [Google CloudSQL][gcloudsql] is highly recommended for production environments. -- **Redis-compatible cache**: An external Redis-compatible cache, such as [Google Memorystore] (https://cloud.google.com/memorystore/docs/redis/), is highly recommended for production deployments. -- **SSL certificate**: An SSL certificate is required for your Seqera instance to handle HTTPS traffic. - - :::caution - HTTP-only implementations **must** set the `TOWER_ENABLE_UNSAFE_MODE=true` environment variable in the Seqera hosting infrastructure to enable user login. HTTP must not be used in production environments. - ::: - -- **Public IP address**: (Optional) A public IP address can be reserved for the Seqera ingress to keep the IP address constant across restarts. - -
- Reserve a public IP address - - 1. Go to **VPC network > External IP addresses** and select **Reserve Static Address**. - 2. Assign a name (such as `tower-ip`). This name will be used later to configure the ingress. - 3. Select the region where your GKE cluster is deployed. - 4. Select **Reserve**. - -
- -### Prerequisites for Docker - -A [Google Compute Engine (GCE)][gce] instance is required to deploy Seqera Enterprise via Docker Compose. See [Google Compute Engine](#google-compute-engine) to provision a VM instance for this purpose. - -### Prerequisites for GKE - -A [Google Kubernetes Engine (GKE)][gke] cluster is required to deploy Seqera Enterprise via Kubernetes. See the [GKE documentation][gke-docs] to provision your own cluster. - -:::note -Seqera doesn't currently support GKE Autopilot due to a privilege issue with the Redis deployment. However, you can achieve most of the same behavior with a Standard cluster by enabling autoscaling and node auto-provisioning. -::: - -## GCP setup - -This section provides step-by-step instructions for some commonly used GCP services for Seqera deployment. See the [GCP documentation][gcp-docs] for up-to-date instructions and contact [GCP support][gcp-support] if you have any issues with provisioning GCP resources. - -### Google CloudSQL - -Create a Google CloudSQL instance with the following attributes: -- MySQL 8.0 -- At least **2 vCPUs**, **8 GB** memory, and **30 GB SSD** storage -- Private IP - -:::caution -The recommended machine type and storage requirements depend on the number of parallel pipelines you expect to run. -::: - - - - -1. See [Create a MySQL instance][gcloudsql-create] for Cloud console instructions. -1. After the instance has been created, select the instance, then **Databases**. Create a new database named `tower`. -1. Note the Private IP address of the instance as it must be supplied to the `TOWER_DB_URL` environment variable. - - - - -See [Create a MySQL instance][gcloudsql-create] for gcloud CLI instructions. - -1. Create your MySQL instance with the following command: - ```bash - gcloud sql instances create INSTANCE_NAME \ - --database-version=MYSQL_8_0 \ - --cpu=2 \ - --memory=8GB \ - --storage-size=30GB \ - --region=us-central1 - ``` -1. Note the private IP address as it must be supplied to the `TOWER_DB_URL` environment variable during Seqera configuration. -1. Set the password for the root MySQL user: - ```bash - gcloud sql users set-password root \ - --host=% \ - --instance INSTANCE_NAME \ - --password PASSWORD - ``` -1. Create a database named `tower` on the instance: - ```bash - gcloud sql databases create tower \ - --instance=INSTANCE_NAME \ - ``` - - - - -### Google Compute Engine - -Create a VM instance with these attributes: -- At least **2 vCPUs** and **8 GB** memory -- HTTP traffic enabled. By default, the frontend is exposed to port 8000, so you must add a firewall rule to the underlying VPC network to allow traffic on port 8000 after VM creation. -- SSH enabled (to allow connection to the VM). If you experience issues with SSH, or would like to set up IAP SSH, see [TCP forward to IAP][tcp-iap]. - - - - -See [Create a VM instance from a public image][gcp-vm-public] for Cloud console instructions. - - - - -1. Run `gcloud compute images list` to view a list of available public OS images. Note the name of the image you wish to use and the name of the project that contains it. -1. Create your VM with the following command (you can use either `--image` or `--image-family`, only one is required): - ```gcloud - gcloud compute instances create VM_NAME \ - [--image=IMAGE | --image-family=IMAGE_FAMILY] \ - --image-project=IMAGE_PROJECT - --machine-type=MACHINE_TYPE - ``` - Replace `VM_NAME`, `IMAGE`, `IMAGE_FAMILY`, `IMAGE_PROJECT`, and `MACHINE_TYPE` with your VM details. -1. Run `gcloud compute instances describe VM_NAME` to verify that Compute Engine created the VM. - - - - -After you have created your VM instance: - -1. Connect to the machine using SSH. -1. [Install Docker][install-docker]. -1. Confirm that Docker Compose is installed: - ```bash - docker compose version - Docker Compose version v2.24.1 - ``` - -## Seqera container images - -Seqera Enterprise is distributed as a collection of container images available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Refer to the instructions in the [Common prerequisites](./common.md#vendoring-seqera-container-images-to-your-own-registry) page to replicate the required images to your internal container registry for High Availability or for air-gapped environments. - -## Next steps - -See [Configuration](../configuration/overview). - -[gce]: https://cloud.google.com/compute -[gcloudsql]: https://cloud.google.com/sql/docs/mysql/quickstart -[gcloudsql-create]: https://cloud.google.com/sql/docs/mysql/create-instance#create-2nd-gen -[gcp-docs]: https://cloud.google.com/docs -[gcp-support]: https://cloud.google.com/support-hub -[gcp-vm-public]: https://cloud.google.com/compute/docs/instances/create-start-instance#publicimage -[gke]: https://cloud.google.com/kubernetes-engine -[gke-docs]: https://cloud.google.com/kubernetes-engine/docs -[install-docker]: https://docs.docker.com/engine/install/debian/ -[mailgun]: https://cloud.google.com/compute/docs/tutorials/sending-mail/using-mailgun -[mailjet]: https://cloud.google.com/compute/docs/tutorials/sending-mail/using-mailjet -[sendgrid]: https://cloud.google.com/compute/docs/tutorials/sending-mail/using-sendgrid -[tcp-iap]: https://cloud.google.com/iap/docs/using-tcp-forwarding diff --git a/platform-enterprise_docs/enterprise/prerequisites/on-prem.md b/platform-enterprise_docs/enterprise/prerequisites/on-prem.md deleted file mode 100644 index 34a3211ed..000000000 --- a/platform-enterprise_docs/enterprise/prerequisites/on-prem.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "On-prem" -description: Prerequisites for on-premises deployments -date: "12 Apr 2023" -tags: [on-prem, prerequisites, configuration] ---- - -This page details the prerequisites for deploying Seqera Platform Enterprise to your on-premises infrastructure. - -See [Docker Compose](../docker-compose) for instructions to deploy via Docker Compose. - -See [Kubernetes](../kubernetes) for instructions to deploy via Kubernetes. - -## Prerequisites - -You must satisfy the requirements for your installation: - -- **SMTP server**: An SMTP server is required to send emails from your Seqera instance. - - If you don't have your own mail server, you can use an external service from a cloud provider. Visit the provider's corresponding **Prerequisites** page for more information and consult your IT team to select the most suitable solution for your organization. - -- **MySQL database**: A database external to your Docker Compose or Kubernetes environment is highly recommended for production deployments. - - If you don't have your own database service, use an external service from a cloud provider. Visit the provider's corresponding **Prerequisites** page for more information and consult your IT team to select the most suitable solution for your organization. - - To use an external database, you must create a MySQL user and database manually. See [Configuration](../configuration/overview#seqera-and-redis-databases) for more details. - -- **Redis cache**: A Redis-compatible cache external to your Docker Compose or Kubernetes environment is highly recommended for production deployments. - - If you don't have your own Redis service, use an external service from a cloud provider. Visit the provider's corresponding **Prerequisites** page for more information and consult your IT team to select the most suitable solution for your organization. - - See [Configuration](../configuration/overview#seqera-and-redis-databases) for more details. - -- **(Optional) SSL certificate**: An SSL certificate is required for your Seqera instance to handle HTTPS traffic. - -:::caution -HTTP-only implementations **must** set the `TOWER_ENABLE_UNSAFE_MODE=true` environment variable in the Seqera hosting infrastructure to enable user login. HTTP must not be used in production environments. -::: - -## Seqera container images - -Seqera Enterprise is distributed as a collection of container images available through the Seqera container registry [`cr.seqera.io`](https://cr.seqera.io). Refer to the instructions in the [Common prerequisites](./common.md#vendoring-seqera-container-images-to-your-own-registry) page to replicate the required images to your internal container registry for High Availability or for air-gapped environments. - -## Next steps - -See [Configuration](../configuration/overview.mdx). diff --git a/platform-enterprise_docs/enterprise/studios-docker-compose.md b/platform-enterprise_docs/enterprise/studios-docker-compose.md new file mode 100644 index 000000000..582c3aaaf --- /dev/null +++ b/platform-enterprise_docs/enterprise/studios-docker-compose.md @@ -0,0 +1,85 @@ +--- +title: "Studios Docker Compose deployment" +description: Deploy Studios with Docker Compose +date: "12 Apr 2023" +tags: [docker, compose, studios, deployment] +--- + +This guide describes how to deploy Studios for Seqera Platform Enterprise with Docker Compose. + +## Prerequisites + +Before you begin, you need: +- A running Seqera Platform Enterprise Docker Compose deployment +- A wildcard TLS certificate for your domain (e.g., `*.example.com`) +- A wildcard DNS record (e.g., `*.example.com`) +- Inbound traffic allowed on port 9090 +- Traffic on port 9090 through your load balancer + +## Procedure + +1. Create a folder for Connect metadata: + + ```bash + mkdir -p $HOME/.tower/connect + chmod 777 $HOME/.tower/connect + ``` + +1. Download the Studios [environment configuration file](./_templates/docker/data-studios.env). + +1. Create an initial OIDC registration token: + + ```bash + oidc_registration_token=$(openssl rand -base64 32 | tr -d /=+ | cut -c -32) + ``` + +1. Generate an RSA public/private key pair: + + ```bash + openssl genrsa -out private.pem 2048 + openssl rsa -pubout -in private.pem -out public.pem + ``` + +1. Download the [data-studios-rsa.pem](./_templates/docker/data-studios-rsa.pem) file and replace its contents with the content of your private and public key files (private key on top, public key directly beneath it). Save as `data-studios-rsa.pem` in the same directory as your `docker-compose.yml`. + +1. Open `docker-compose.yml` and uncomment the volume mount for the PEM key file for the `backend` and `cron` services: + + ```yaml + volumes: + - $PWD/tower.yml:/tower.yml + - $PWD/data-studios-rsa.pem:/data-studios-rsa.pem + ``` + +1. Open `data-studios.env` and set the following: + + - Uncomment the `connect-proxy` and `connect-server` services. + - `PLATFORM_URL`: The same value as `TOWER_SERVER_URL` (e.g., `https://example.com`). + - `CONNECT_PROXY_URL`: A URL for the connect proxy subdomain (e.g., `https://connect.example.com`). + - `CONNECT_OIDC_CLIENT_REGISTRATION_TOKEN`: The same value as `oidc_registration_token`. + +1. Open `tower.env` and set the following: + + - `TOWER_DATA_EXPLORER_ENABLED`: Set to `true`. + - `TOWER_DATA_STUDIO_CONNECT_URL`: The URL of the Studios connect proxy (e.g., `https://connect.example.com/`). + - `TOWER_OIDC_REGISTRATION_INITIAL_ACCESS_TOKEN`: The same value as `oidc_registration_token`. + - `TOWER_OIDC_PEM_PATH`: The file path to the PEM certificate (e.g., `/data-studios-rsa.pem`). + +1. Edit `tower.yml` to enable Studios: + + ```yaml + tower: + data-studio: + allowed-workspaces: null + ``` + +1. Start your Platform instance: + + ```bash + docker compose up -d + ``` + +1. Verify Studios is available by logging into Seqera and navigating to an organizational workspace. The **Studios** tab should be displayed. + +## Configuration + +See [Studios deployment](./studios) for DNS configuration, workspace availability, and environment image options. diff --git a/platform-enterprise_docs/enterprise/studios-kubernetes.md b/platform-enterprise_docs/enterprise/studios-kubernetes.md new file mode 100644 index 000000000..1b01c65c5 --- /dev/null +++ b/platform-enterprise_docs/enterprise/studios-kubernetes.md @@ -0,0 +1,123 @@ +--- +title: "Studios Kubernetes deployment" +description: Deploy Studios on Kubernetes +date: "12 Apr 2023" +tags: [kubernetes, studios, deployment] +--- + +This guide describes how to deploy Studios for Seqera Platform Enterprise on Kubernetes. + +## Prerequisites + +Before you begin, you need: +- A running Seqera Platform Enterprise Kubernetes deployment +- A wildcard TLS certificate for your domain (e.g., `*.example.com`) +- A wildcard DNS record (e.g., `*.example.com`) + +## Procedure + +1. Download the Kubernetes manifests for the Studios service: + + - [Proxy](./_templates/k8s/data_studios/proxy.yml) + - [Server](./_templates/k8s/data_studios/server.yml) + +1. Change your Kubernetes context to the namespace where your Platform instance runs: + + ```bash + kubectl config set-context --current --namespace= + ``` + +1. Edit the `server.yml` file and set the `CONNECT_REDIS_ADDRESS` environment variable to the hostname or IP address of the Redis server configured for Platform. + +1. Create an initial OIDC registration token: + + ```bash + oidc_registration_token=$(openssl rand -base64 32 | tr -d /=+ | cut -c -32) + ``` + +1. Edit the `proxy.yml` file and set the following variables: + + - `CONNECT_REDIS_ADDRESS`: The hostname or IP address of the Redis server configured for Seqera. + - `CONNECT_PROXY_URL`: A URL for the connect proxy subdomain (e.g., `https://connect.example.com`). + - `PLATFORM_URL`: The base URL for your installation (e.g., `https://example.com/`). + - `CONNECT_OIDC_CLIENT_REGISTRATION_TOKEN`: The same value as the `oidc_registration_token` value created previously. + +1. Edit your `ingress.eks.yml` file: + + - Uncomment the `host` section at the bottom of the file. + - Replace `` with the base domain of your installation. + +1. Generate an RSA public/private key pair: + + ```bash + openssl genrsa -out private.pem 2048 + openssl rsa -pubout -in private.pem -out public.pem + ``` + +1. Download the [data-studios-rsa.pem](./_templates/docker/data-studios-rsa.pem) file and replace its contents with the content of your private and public key files (private key on top, public key directly beneath it). + +1. Apply a base64 encoding to the PEM file: + + ```bash + base64_pem=$(cat data-studios-rsa.pem | base64 -w0) + ``` + +1. Create a secret file named `secret.yml`: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: platform-oidc-certs + namespace: platform-stage + data: + oidc.pem: + ``` + +1. Create the secret: + + ```bash + kubectl apply -f secret.yml + ``` + +1. Edit the `tower-svc.yml` file and uncomment the `volumes.cert-volume`, `volumeMounts.cert-volume`, and `env.TOWER_OIDC_PEM_PATH` fields. + +1. Edit the ConfigMap named `platform-backend-cfg` in the `configmap.yml`: + + - `TOWER_DATA_STUDIO_CONNECT_URL`: The URL of the Studios connect proxy (e.g., `https://connect.example.com/`). + - `TOWER_OIDC_REGISTRATION_INITIAL_ACCESS_TOKEN`: The same value as the `oidc_registration_token` value created previously. + +1. Edit the ConfigMap named `tower-yml` in the `configmap.yml`: + + ```yaml + data: + tower.yml: |- + tower: + data-studio: + allowed-workspaces: null + ``` + +1. Apply the updated configuration: + + ```bash + kubectl apply -f configmap.yml + kubectl apply -f tower-svc.yml + ``` + +1. Restart the cron and backend services: + + ```bash + kubectl rollout restart deployment/backend deployment/cron + ``` + +1. Apply the Studios manifests: + + ```bash + kubectl apply -f ingress.aks.yml proxy.yml server.yml + ``` + +1. Verify Studios is available by logging into Seqera and navigating to an organizational workspace. The **Studios** tab should be displayed. + +## Configuration + +See [Studios deployment](./studios) for DNS configuration, workspace availability, and environment image options. From 06cc186c14b46bf4fbb0399280bdf361683223e0 Mon Sep 17 00:00:00 2001 From: Gavin Elder Date: Mon, 22 Dec 2025 22:19:46 +0000 Subject: [PATCH 2/5] docs: refactor enterprise installation docs --- .../enterprise-sidebar.json | 14 ++++ .../configuration/pipeline_optimization.md | 2 +- .../enterprise/groundswell-docker-compose.md | 79 +++++++++++++++++++ .../enterprise/groundswell-kubernetes.md | 65 +++++++++++++++ .../enterprise/install-groundswell.md | 25 ++++++ .../enterprise/install-platform.md | 24 ++++++ .../enterprise/install-studios.md | 26 ++++++ .../enterprise/studios-docker-compose.md | 2 +- .../enterprise/studios-kubernetes.md | 2 +- .../enterprise/studios.md | 2 +- 10 files changed, 237 insertions(+), 4 deletions(-) create mode 100644 platform-enterprise_docs/enterprise/groundswell-docker-compose.md create mode 100644 platform-enterprise_docs/enterprise/groundswell-kubernetes.md create mode 100644 platform-enterprise_docs/enterprise/install-groundswell.md create mode 100644 platform-enterprise_docs/enterprise/install-platform.md create mode 100644 platform-enterprise_docs/enterprise/install-studios.md diff --git a/platform-enterprise_docs/enterprise-sidebar.json b/platform-enterprise_docs/enterprise-sidebar.json index 6ae5ac8b0..2f49876c2 100644 --- a/platform-enterprise_docs/enterprise-sidebar.json +++ b/platform-enterprise_docs/enterprise-sidebar.json @@ -14,6 +14,10 @@ "type": "category", "label": "Platform", "collapsed": true, + "link": { + "type": "doc", + "id": "enterprise/install-platform" + }, "items": [ "enterprise/docker-compose", "enterprise/kubernetes", @@ -24,6 +28,10 @@ "type": "category", "label": "Studios", "collapsed": true, + "link": { + "type": "doc", + "id": "enterprise/install-studios" + }, "items": [ "enterprise/studios-docker-compose", "enterprise/studios-kubernetes", @@ -34,7 +42,13 @@ "type": "category", "label": "Pipeline optimization", "collapsed": true, + "link": { + "type": "doc", + "id": "enterprise/install-groundswell" + }, "items": [ + "enterprise/groundswell-docker-compose", + "enterprise/groundswell-kubernetes", "enterprise/configuration/pipeline_optimization" ] }, diff --git a/platform-enterprise_docs/enterprise/configuration/pipeline_optimization.md b/platform-enterprise_docs/enterprise/configuration/pipeline_optimization.md index 43d00ba69..4b028b5c0 100644 --- a/platform-enterprise_docs/enterprise/configuration/pipeline_optimization.md +++ b/platform-enterprise_docs/enterprise/configuration/pipeline_optimization.md @@ -1,5 +1,5 @@ --- -title: "Pipeline resource optimization" +title: "Pipeline optimization" description: "Configure pipeline resource optimization in your Seqera Enterprise deployment." date: "12 Feb 2024" tags: [compute, resource, optimization, configuration] diff --git a/platform-enterprise_docs/enterprise/groundswell-docker-compose.md b/platform-enterprise_docs/enterprise/groundswell-docker-compose.md new file mode 100644 index 000000000..2e7ae492f --- /dev/null +++ b/platform-enterprise_docs/enterprise/groundswell-docker-compose.md @@ -0,0 +1,79 @@ +--- +title: "Pipeline optimization: Docker Compose" +description: Deploy pipeline resource optimization with Docker Compose +date: "12 Apr 2023" +tags: [docker, compose, groundswell, deployment] +--- + +This guide describes how to deploy the pipeline resource optimization service (Groundswell) for Seqera Platform Enterprise with Docker Compose. + +## Prerequisites + +Before you begin, you need: +- A running Seqera Platform Enterprise Docker Compose deployment +- Access to your MySQL database + +## New installation + +1. Set the `TOWER_ENABLE_GROUNDSWELL` environment variable in `tower.env` to `true`. This enables the service at the default URL `http://groundswell:8090`. + + To use a custom URL, set `GROUNDSWELL_SERVER_URL` instead. + +2. In your [docker-compose.yml](../_templates/docker/docker-compose.yml) file, uncomment the `groundswell` section. + +3. To create a schema on the local MySQL container, uncomment the `init.sql` script in the `volumes` section. + +4. Download the [init.sql](../_templates/docker/init.sql) file and store it in the mount path of your `docker-compose.yml`. + +5. Start your Platform instance: + + ```bash + docker compose up -d + ``` + +## Existing installation + +1. Set the `TOWER_ENABLE_GROUNDSWELL` environment variable in `tower.env` to `true`. + + To use a custom URL, set `GROUNDSWELL_SERVER_URL` instead. + +2. In your [docker-compose.yml](../_templates/docker/docker-compose.yml) file, uncomment the `groundswell` section. + +3. Create the Groundswell database schema: + + ```sql + CREATE DATABASE IF NOT EXISTS `swell`; + CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; + GRANT ALL PRIVILEGES ON *.* TO 'swell'@'%'; + FLUSH PRIVILEGES; + ``` + + For managed database services (RDS, Cloud SQL, etc.): + + ```sql + CREATE DATABASE IF NOT EXISTS `swell`; + CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; + GRANT ALL PRIVILEGES ON `%`.* TO 'swell'@'%'; + FLUSH PRIVILEGES; + ``` + +4. Download the [groundswell.env](../_templates/docker/groundswell.env) file and update the database URLs: + + ```env + TOWER_DB_URL=mysql://db:3306/tower + SWELL_DB_URL=mysql://db:3306/swell + ``` + +5. Restart your Platform instance: + + ```bash + docker compose up -d + ``` + +## Verify + +When pipeline optimization is active, pipelines with at least one successful run display a lightbulb icon in the Launchpad. + +## Configuration + +See [Pipeline resource optimization](./configuration/pipeline_optimization) for additional configuration options. diff --git a/platform-enterprise_docs/enterprise/groundswell-kubernetes.md b/platform-enterprise_docs/enterprise/groundswell-kubernetes.md new file mode 100644 index 000000000..5c41c18bd --- /dev/null +++ b/platform-enterprise_docs/enterprise/groundswell-kubernetes.md @@ -0,0 +1,65 @@ +--- +title: "Pipeline optimization: Kubernetes" +description: Deploy pipeline resource optimization on Kubernetes +date: "12 Apr 2023" +tags: [kubernetes, groundswell, deployment] +--- + +This guide describes how to deploy the pipeline resource optimization service (Groundswell) for Seqera Platform Enterprise on Kubernetes. + +## Prerequisites + +Before you begin, you need: +- A running Seqera Platform Enterprise Kubernetes deployment +- Access to your MySQL database + +## Procedure + +1. Download the [groundswell manifest](../_templates/k8s/groundswell.yml). + +2. Set `TOWER_ENABLE_GROUNDSWELL=true` in your `configmap.yml`. + + To use a custom URL, set `GROUNDSWELL_SERVER_URL` instead. + +3. Create the Groundswell database schema: + + ```sql + CREATE DATABASE IF NOT EXISTS `swell`; + CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; + GRANT ALL PRIVILEGES ON *.* TO 'swell'@'%'; + FLUSH PRIVILEGES; + ``` + + For managed database services (RDS, Cloud SQL, etc.): + + ```sql + CREATE DATABASE IF NOT EXISTS `swell`; + CREATE USER 'swell'@'%' IDENTIFIED BY 'swell'; + GRANT ALL PRIVILEGES ON `%`.* TO 'swell'@'%'; + FLUSH PRIVILEGES; + ``` + +4. Update the Groundswell ConfigMap (`tower-groundswell-cfg`) with your database credentials. + +5. Apply the manifests: + + ```bash + kubectl apply -f configmap.yml + kubectl apply -f groundswell.yml + ``` + +6. Restart the backend: + + ```bash + kubectl rollout restart deployment/backend + ``` + +The initContainers process waits for both databases to be ready before starting the migration and optimization service. + +## Verify + +When pipeline optimization is active, pipelines with at least one successful run display a lightbulb icon in the Launchpad. + +## Configuration + +See [Pipeline resource optimization](./configuration/pipeline_optimization) for additional configuration options. diff --git a/platform-enterprise_docs/enterprise/install-groundswell.md b/platform-enterprise_docs/enterprise/install-groundswell.md new file mode 100644 index 000000000..ce899648e --- /dev/null +++ b/platform-enterprise_docs/enterprise/install-groundswell.md @@ -0,0 +1,25 @@ +--- +title: "Pipeline optimization" +description: Install pipeline resource optimization for Seqera Platform Enterprise +date: "12 Apr 2023" +tags: [groundswell, pipeline, optimization, installation, deployment] +--- + +Pipeline resource optimization (Groundswell) uses resource usage data from previous workflow runs to optimize subsequent runs. Deploy after your Platform installation is complete. + +## Deployment options + +| Method | Guide | +| :----- | :---- | +| Docker Compose | [Pipeline optimization: Docker Compose](./groundswell-docker-compose) | +| Kubernetes | [Pipeline optimization: Kubernetes](./groundswell-kubernetes) | + +## Prerequisites + +Before you begin, you need: +- A running Seqera Platform Enterprise deployment +- Access to your MySQL database + +## Configuration + +See [Pipeline optimization](./configuration/pipeline_optimization) for additional configuration options. diff --git a/platform-enterprise_docs/enterprise/install-platform.md b/platform-enterprise_docs/enterprise/install-platform.md new file mode 100644 index 000000000..82adc4449 --- /dev/null +++ b/platform-enterprise_docs/enterprise/install-platform.md @@ -0,0 +1,24 @@ +--- +title: "Platform" +description: Install Seqera Platform Enterprise +date: "12 Apr 2023" +tags: [installation, deployment] +--- + +Seqera Platform Enterprise can be deployed using Docker Compose, Kubernetes, or Helm. + +## Deployment options + +| Method | Use case | +| :----- | :------- | +| [Docker Compose](./docker-compose) | Evaluation, development, small production workloads | +| [Kubernetes](./kubernetes) | Production workloads requiring high availability | +| [Helm](./helm) | Kubernetes deployments using Helm charts | + +## Prerequisites + +Before you begin, you need: +- A MySQL 8 database +- A Redis 7 instance + +See each deployment guide for detailed requirements. diff --git a/platform-enterprise_docs/enterprise/install-studios.md b/platform-enterprise_docs/enterprise/install-studios.md new file mode 100644 index 000000000..c381f4f5f --- /dev/null +++ b/platform-enterprise_docs/enterprise/install-studios.md @@ -0,0 +1,26 @@ +--- +title: "Studios" +description: Install Studios for Seqera Platform Enterprise +date: "12 Apr 2023" +tags: [studios, installation, deployment] +--- + +Studios provides interactive analysis environments within Seqera Platform. Deploy Studios after your Platform installation is complete. + +## Deployment options + +| Method | Guide | +| :----- | :---- | +| Docker Compose | [Studios: Docker Compose](./studios-docker-compose) | +| Kubernetes | [Studios: Kubernetes](./studios-kubernetes) | + +## Prerequisites + +Before you begin, you need: +- A running Seqera Platform Enterprise deployment +- A wildcard TLS certificate for your domain +- A wildcard DNS record + +## Configuration + +See [Studios](./studios) for DNS configuration, workspace availability, and environment image options. diff --git a/platform-enterprise_docs/enterprise/studios-docker-compose.md b/platform-enterprise_docs/enterprise/studios-docker-compose.md index 582c3aaaf..1545ab384 100644 --- a/platform-enterprise_docs/enterprise/studios-docker-compose.md +++ b/platform-enterprise_docs/enterprise/studios-docker-compose.md @@ -1,5 +1,5 @@ --- -title: "Studios Docker Compose deployment" +title: "Studios: Docker Compose" description: Deploy Studios with Docker Compose date: "12 Apr 2023" tags: [docker, compose, studios, deployment] diff --git a/platform-enterprise_docs/enterprise/studios-kubernetes.md b/platform-enterprise_docs/enterprise/studios-kubernetes.md index 1b01c65c5..779e688cb 100644 --- a/platform-enterprise_docs/enterprise/studios-kubernetes.md +++ b/platform-enterprise_docs/enterprise/studios-kubernetes.md @@ -1,5 +1,5 @@ --- -title: "Studios Kubernetes deployment" +title: "Studios: Kubernetes" description: Deploy Studios on Kubernetes date: "12 Apr 2023" tags: [kubernetes, studios, deployment] diff --git a/platform-enterprise_docs/enterprise/studios.md b/platform-enterprise_docs/enterprise/studios.md index d49e78506..d79dd2090 100644 --- a/platform-enterprise_docs/enterprise/studios.md +++ b/platform-enterprise_docs/enterprise/studios.md @@ -1,5 +1,5 @@ --- -title: "Studios deployment" +title: "Studios" description: Deploy Seqera Platform with Studios date created: "2025-03-17" last updated: "2025-12-05" From 2b0ede16cb482b1262f23999545c3c3e57dfc0f8 Mon Sep 17 00:00:00 2001 From: Gavin Elder Date: Mon, 22 Dec 2025 23:47:20 +0000 Subject: [PATCH 3/5] docs: refactor enterprise installation docs --- platform-enterprise_docs/enterprise-sidebar.json | 7 +++---- platform-enterprise_docs/enterprise/docker-compose.md | 2 +- platform-enterprise_docs/enterprise/helm.md | 2 +- platform-enterprise_docs/enterprise/kubernetes.md | 2 +- 4 files changed, 6 insertions(+), 7 deletions(-) diff --git a/platform-enterprise_docs/enterprise-sidebar.json b/platform-enterprise_docs/enterprise-sidebar.json index 2f49876c2..6a7b1ca5b 100644 --- a/platform-enterprise_docs/enterprise-sidebar.json +++ b/platform-enterprise_docs/enterprise-sidebar.json @@ -19,8 +19,8 @@ "id": "enterprise/install-platform" }, "items": [ - "enterprise/docker-compose", "enterprise/kubernetes", + "enterprise/docker-compose", "enterprise/helm" ] }, @@ -33,8 +33,8 @@ "id": "enterprise/install-studios" }, "items": [ - "enterprise/studios-docker-compose", "enterprise/studios-kubernetes", + "enterprise/studios-docker-compose", "enterprise/studios" ] }, @@ -47,8 +47,8 @@ "id": "enterprise/install-groundswell" }, "items": [ - "enterprise/groundswell-docker-compose", "enterprise/groundswell-kubernetes", + "enterprise/groundswell-docker-compose", "enterprise/configuration/pipeline_optimization" ] }, @@ -58,7 +58,6 @@ "collapsed": true, "items": [ "enterprise/configuration/overview", - "enterprise/configuration/authentication", "enterprise/configuration/networking", "enterprise/configuration/ssl_tls", "enterprise/configuration/reverse_proxy", diff --git a/platform-enterprise_docs/enterprise/docker-compose.md b/platform-enterprise_docs/enterprise/docker-compose.md index d6fcd09a3..25da5a8e4 100644 --- a/platform-enterprise_docs/enterprise/docker-compose.md +++ b/platform-enterprise_docs/enterprise/docker-compose.md @@ -1,5 +1,5 @@ --- -title: "Docker Compose" +title: "Platform: Docker Compose" description: Deploy Seqera Platform Enterprise with Docker Compose date: "12 Feb 2024" tags: [docker, compose, deployment] diff --git a/platform-enterprise_docs/enterprise/helm.md b/platform-enterprise_docs/enterprise/helm.md index 21f388e90..5ba7db94a 100644 --- a/platform-enterprise_docs/enterprise/helm.md +++ b/platform-enterprise_docs/enterprise/helm.md @@ -1,5 +1,5 @@ --- -title: "Helm" +title: "Platform: Helm" description: Deploy Seqera Platform Enterprise on Kubernetes with Helm date created: "2025-11-21" tags: [helm, deployment, installation, kubernetes] diff --git a/platform-enterprise_docs/enterprise/kubernetes.md b/platform-enterprise_docs/enterprise/kubernetes.md index b2b4b0e04..601adcb4b 100644 --- a/platform-enterprise_docs/enterprise/kubernetes.md +++ b/platform-enterprise_docs/enterprise/kubernetes.md @@ -1,5 +1,5 @@ --- -title: "Kubernetes" +title: "Platform: Kubernetes" description: Deploy Seqera Platform Enterprise with Kubernetes date: "21 Apr 2023" tags: [kubernetes, deployment] From e3567a2e4ca5f17b43baedb9cfa4e711d6e83dc0 Mon Sep 17 00:00:00 2001 From: Gavin Elder Date: Mon, 22 Dec 2025 23:49:58 +0000 Subject: [PATCH 4/5] docs: refactor authentication --- .../enterprise-sidebar.json | 16 ++ .../configuration/authentication.md | 193 ------------------ .../configuration/authentication/entra.md | 65 ++++++ .../configuration/authentication/github.md | 49 +++++ .../configuration/authentication/google.md | 50 +++++ .../configuration/authentication/keycloak.md | 51 +++++ .../configuration/authentication/okta.md | 57 ++++++ .../configuration/authentication/overview.md | 128 ++++++++++++ 8 files changed, 416 insertions(+), 193 deletions(-) delete mode 100644 platform-enterprise_docs/enterprise/configuration/authentication.md create mode 100644 platform-enterprise_docs/enterprise/configuration/authentication/entra.md create mode 100644 platform-enterprise_docs/enterprise/configuration/authentication/github.md create mode 100644 platform-enterprise_docs/enterprise/configuration/authentication/google.md create mode 100644 platform-enterprise_docs/enterprise/configuration/authentication/keycloak.md create mode 100644 platform-enterprise_docs/enterprise/configuration/authentication/okta.md create mode 100644 platform-enterprise_docs/enterprise/configuration/authentication/overview.md diff --git a/platform-enterprise_docs/enterprise-sidebar.json b/platform-enterprise_docs/enterprise-sidebar.json index 6a7b1ca5b..f886a1906 100644 --- a/platform-enterprise_docs/enterprise-sidebar.json +++ b/platform-enterprise_docs/enterprise-sidebar.json @@ -58,6 +58,22 @@ "collapsed": true, "items": [ "enterprise/configuration/overview", + { + "type": "category", + "label": "Authentication", + "collapsed": true, + "link": { + "type": "doc", + "id": "enterprise/configuration/authentication/overview" + }, + "items": [ + "enterprise/configuration/authentication/github", + "enterprise/configuration/authentication/google", + "enterprise/configuration/authentication/keycloak", + "enterprise/configuration/authentication/entra", + "enterprise/configuration/authentication/okta" + ] + }, "enterprise/configuration/networking", "enterprise/configuration/ssl_tls", "enterprise/configuration/reverse_proxy", diff --git a/platform-enterprise_docs/enterprise/configuration/authentication.md b/platform-enterprise_docs/enterprise/configuration/authentication.md deleted file mode 100644 index 6b737c8d1..000000000 --- a/platform-enterprise_docs/enterprise/configuration/authentication.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: "Authentication" -description: Seqera configuration options for authentication -date created: "2023-04-21" -last updated: "2025-11-19" -tags: [authentication, configuration] ---- - -Seqera Platform supports email and various OAuth providers for login authentication. - -:::note -Platform login sessions remain active as long as the application browser window remains open and active. When the browser window is terminated, automatic logout occurs within 6 hours by default. -::: - -## OpenID Connect configuration - -Seqera Enterprise can be configured to integrate with several authentication providers to enable single sign-on (SSO) login. - -Configure OIDC authentication with the following environment variables: - -- `TOWER_OIDC_CLIENT`: The client ID provided by your authentication service. -- `TOWER_OIDC_SECRET`: The client secret provided by your authentication service. -- `TOWER_OIDC_ISSUER`: The authentication service URL to which Seqera connects to authenticate the sign-in request. - -Some providers require the full authentication service URL while others require only the SSO root domain (without the trailing sub-directories). - -In your OpenID provider settings, specify the following URL as a callback address or authorized redirect: - -``` -https:///oauth/callback/oidc -``` - -## Identity providers - -The following identity providers are currently supported: - -- GitHub -- Google -- Keycloak -- Entra -- Okta - -### GitHub identity provider - -To use GitHub as SSO provider for Seqera: - -1. Register your Seqera instance as a [GitHub OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) - in your organization settings page. - -2. When creating the OAuth App, specify the following path as callback URL: `https:///oauth/callback/github` (replace `` with the domain name of your deployment). - -3. Include the following variables in the backend environment configuration: - - - `TOWER_GITHUB_CLIENT`: The client ID provided by GitHub when registering the new OAuth App. - - `TOWER_GITHUB_SECRET`: The client secret provided by GitHub when registering the new OAuth App. - -### Google Cloud identity provider - -To use Google as the identity provider for Seqera: - -1. Visit the [Google Cloud console](https://console.developers.google.com) and create a new project. -2. From the sidebar, select the **Credentials** tab. -3. Select **Create credentials > OAuth client ID**. -4. On the next page, select **Web Application** type. -5. Enter the redirect URL: `https:///oauth/callback/google`. Replace `` with the domain name of your deployment. -6. Confirm the operation. You'll then receive a `client ID` and `secret ID`. -7. Include the `client ID` and `secret ID` in the following variables in the Seqera backend environment configuration: - -- `TOWER_GOOGLE_CLIENT`: The client ID provided by Google above. -- `TOWER_GOOGLE_SECRET`: The client secret provided by Google above. - -### Keycloak identity provider - -To use [Keycloak](https://www.keycloak.org/) as the identity provider for Seqera, configure a new client in your Keycloak service with these steps: - -1. In the **Realm settings**, ensure the **Endpoints** field includes _OpenID Endpoint Configuration_. -2. Open the **Client** page and select **Create** to set up a new client for Seqera. -3. In the **Settings** tag, include the following fields: - - **Client Id**: An ID of your choice, e.g., `seqera` - - **Enabled**: `ON` - - **Client Protocol**: `openid-connect` - - **Access Type**: `confidential` - - **Standard Flow Enabled**: `ON` - - **Implicit Flow Enabled**: `OFF` - - **Direct Access Grants Enabled**: `ON` - - **Valid Redirect URIs**: https:///\//oauth/callback/oidc, e.g., `http://localhost:8000/oauth/callback/oidc` -4. Select **Save**. -5. In the **Credentials** tab, note the **Secret** field. -6. In the **Keys** tab, set the field **Use JWKS URL** to `OFF`. -7. Complete the setup in Seqera by adding the following environment variables to your configuration: - - - `TOWER_OIDC_CLIENT`: The client ID assigned in step 3 above. - - `TOWER_OIDC_SECRET`: The contents of the **Secret** field noted in step 5 above. - - `TOWER_OIDC_ISSUER`: The Keycloak issuer URL. Locate this on the **Realm Settings** page, from _OpenID Configuration_ in the **Endpoints** field. From the JSON payload displayed, copy the value associated with `issues`, e.g., `http://localhost:9000/auth/realms/master`. - -### Entra ID OIDC provider - -To use [Entra ID OIDC](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc) as the identity provider for Seqera, configure a new client in your Entra ID service: - -1. Log in to the [Azure portal](https://portal.azure.com/). -2. Go to the **Entra ID** service. -3. Select **Manage Tenants**. -4. Create a new **Tenant**, e.g., `SeqeraOrg`. -5. Select the new tenant. -6. Go to **App Registrations**. -7. Select **New Registration** and specify the following: - - 1. A name for the application. - 2. The scope of user verification (e.g., single tenant, multi-tenant, personal MSFT accounts, etc). - -:::note -The Entra ID app must have user consent settings configured to **Allow user consent for apps** to ensure that admin approval is not required for each application login. See [User consent settings](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/configure-user-consent?pivots=portal#configure-user-consent-settings). -::: - -8. Specify the **Redirect** (callback) URI. - -:::note -This must be an `https://` URI, per Microsoft's requirements. -::: - -9. Open the newly-created app: - - 1. Note the `Application (client) ID` on the **Essentials** table. - 2. Generate **Client credentials** on the **Essentials** table. - 3. Select **Endpoints** and note the OpenID Connect metadata document URI. - -10. Add users to your tenant as required. -11. Complete the setup in Seqera by adding the following environment variables to your configuration: - - ```bash - TOWER_OIDC_CLIENT= - TOWER_OIDC_SECRET= - TOWER_OIDC_ISSUER= (e.g. https://login.microsoftonline.com/000000-0000-0000-00-0000000000000/v2.0) - ``` -12. Add `auth-oidc` to the `MICRONAUT_ENVIRONMENTS` environment variable for both the `cron` and `backend` services. - -:::note -Due to changes in Entra ID's supported authentication methods, users on Seqera Platform version 25.2.3 and below may experience incompatibility. To resolve this, add `MICRONAUT_SECURITY_OAUTH2_CLIENTS_OIDC_OPENID_TOKEN_AUTH_METHOD=client_secret_post` to your `tower.env` file or Kubernetes ConfigMap. -::: - -### Okta identity provider - -To use [Okta](https://www.okta.com/) as the identity provider for Seqera: - -1. Sign in to your Okta organization with your administrator account. -2. From the **Admin Console** side navigation, select **Applications > Applications**. -3. Select **Add Application**. -4. Select **Create New App**. -5. Select the **OpenID Connect** sign-on method. -6. Select **Create**. -7. Enter a name for your new app integration, e.g., `Seqera`. -8. In **Configure OpenID Connect**, add the following redirect URIs: - - - **Sign-in redirect URIs** : `https:///oauth/callback/oidc` - - **Sign-out redirect URIs** : `https:///logout` - -9. Select **Save**. -10. Okta automatically redirects to your new application settings. Complete the setup in Seqera by adding the following environment variables to your configuration: - - - `TOWER_OIDC_CLIENT`: Copy the **Client ID** value from **General > Client Credentials** for the corresponding app client configuration. - - `TOWER_OIDC_SECRET`: Copy the **Client secret** value from **General > Client Credentials** for the corresponding app client configuration. - - `TOWER_OIDC_ISSUER`: Copy the Okta issuer URL from **Sign On > OpenID Connect ID Token** for the corresponding app client configuration. - -:::note -Connection strings can differ based on the issuer type. This should be verified via the Okta console. -::: - -## Configure user access allow list - -When using a public authentication provider such as Google or GitHub, you may need to restrict the access to specific user email addresses or domains. - -Replace `` in the snippets below with `github`, `google`, or `oidc`. `oidc` is used to specify any other authentication service based on OpenID Connect, such as Okta, Entra ID, Keycloak, etc. Include each provider separately if you specify more than one. - -The allow list entries are case-insensitive. - -**Environment variables** - -```env -TOWER_AUTH__ALLOW_LIST=*@foo.com,user1@bar.com -``` - -**tower.yml** - -```yaml - -tower: -auth: - : - allow-list: - - "*@foo.com" - - "me@bar.com" - -``` diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/entra.md b/platform-enterprise_docs/enterprise/configuration/authentication/entra.md new file mode 100644 index 000000000..1145e93db --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/entra.md @@ -0,0 +1,65 @@ +--- +title: "Entra ID" +description: Configure Microsoft Entra ID as an identity provider for Seqera Platform +date: "2023-04-21" +tags: [authentication, entra, azure, oidc] +--- + +Configure [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc) as a single sign-on (SSO) provider for Seqera Platform using OpenID Connect. + +## Prerequisites + +Before you begin, you need: + +- An Azure account with Entra ID access +- Permission to create app registrations + +Ensure you know how to register applications in Entra ID. See Microsoft's documentation on [registering an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) for more information. + +## Register an Entra ID application + +1. In the [Azure portal](https://portal.azure.com/), go to **Entra ID > App Registrations**. +2. Select **New Registration** and specify a name and supported account types. +3. Set the redirect URI to `https:///oauth/callback/oidc` (must be HTTPS). +4. Note the **Application (client) ID** from the app overview. +5. Go to **Certificates & secrets** and create a new client secret. Note the secret value. +6. Go to **Endpoints** and note the OpenID Connect metadata document URI (up to `v2.0`). + +## Configure Seqera + +Add the following environment variables to your Seqera configuration: + +| Variable | Description | +| :------- | :---------- | +| `TOWER_OIDC_CLIENT` | The application (client) ID from step 4 | +| `TOWER_OIDC_SECRET` | The client secret from step 5 | +| `TOWER_OIDC_ISSUER` | The issuer URL from step 6, e.g., `https://login.microsoftonline.com//v2.0` | + +Add `auth-oidc` to the `MICRONAUT_ENVIRONMENTS` environment variable for both the `cron` and `backend` services. + +### User consent settings + +Configure user consent settings to **Allow user consent for apps** to ensure admin approval is not required for each login. See [User consent settings](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/configure-user-consent?pivots=portal#configure-user-consent-settings). + +### Compatibility note + +Users on Seqera Platform version 25.2.3 and below may need to add the following to resolve authentication method incompatibility: + +```env +MICRONAUT_SECURITY_OAUTH2_CLIENTS_OIDC_OPENID_TOKEN_AUTH_METHOD=client_secret_post +``` + +## Restrict access + +To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: + +```yaml +tower: + auth: + oidc: + allow-list: + - "*@your-company.com" + - "specific-user@example.com" +``` + +See [User access allow list](./overview#user-access-allow-list) for more information. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/github.md b/platform-enterprise_docs/enterprise/configuration/authentication/github.md new file mode 100644 index 000000000..630276bbd --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/github.md @@ -0,0 +1,49 @@ +--- +title: "GitHub" +description: Configure GitHub as an identity provider for Seqera Platform +date: "2023-04-21" +tags: [authentication, github, oauth] +--- + +Configure GitHub as a single sign-on (SSO) provider for Seqera Platform. + +## Prerequisites + +Before you begin, you need: + +- A GitHub organization +- Permission to create OAuth Apps in your organization + +Ensure you know how to create a GitHub OAuth app. See GitHub's documentation on [creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) for more information. + +## Create a GitHub OAuth App + +1. In **Profile > Settings > Developer settings**, select **OAuth Apps**. +2. Select **New OAuth App**. +3. Complete the required fields. In the **Authorization callback URL** field, enter `https:///oauth/callback/github`. +4. Note your **Client ID**. +5. Generate a client secret, then note your **Client secret**. + +## Configure Seqera + +Add the following environment variables to your Seqera configuration: + +| Variable | Description | +| :------- | :---------- | +| `TOWER_GITHUB_CLIENT` | The client ID from step 4 | +| `TOWER_GITHUB_SECRET` | The client secret from step 5 | + +## Restrict access + +To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: + +```yaml +tower: + auth: + github: + allow-list: + - "*@your-company.com" + - "specific-user@example.com" +``` + +See [User access allow list](./overview#user-access-allow-list) for more information. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/google.md b/platform-enterprise_docs/enterprise/configuration/authentication/google.md new file mode 100644 index 000000000..cee92b0a2 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/google.md @@ -0,0 +1,50 @@ +--- +title: "Google" +description: Configure Google as an identity provider for Seqera Platform +date: "2023-04-21" +tags: [authentication, google, oauth] +--- + +Configure Google as a single sign-on (SSO) provider for Seqera Platform. + +## Prerequisites + +Before you begin, you need: + +- A Google Cloud account +- Permission to create OAuth credentials in the Google Cloud console + +Ensure you know how to create Google OAuth credentials. See Google's documentation on [setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849) for more information. + +## Create Google OAuth credentials + +1. In the [Google Cloud console](https://console.developers.google.com), create a new project or select an existing one. +2. Go to **APIs & Services > Credentials**. +3. Select **Create credentials > OAuth client ID**. +4. Select **Web Application** as the application type. +5. Add your redirect URI: `https:///oauth/callback/google`. +6. Note your **Client ID** and **Client secret**. + +## Configure Seqera + +Add the following environment variables to your Seqera configuration: + +| Variable | Description | +| :------- | :---------- | +| `TOWER_GOOGLE_CLIENT` | The client ID from step 6 | +| `TOWER_GOOGLE_SECRET` | The client secret from step 6 | + +## Restrict access + +To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: + +```yaml +tower: + auth: + google: + allow-list: + - "*@your-company.com" + - "specific-user@example.com" +``` + +See [User access allow list](./overview#user-access-allow-list) for more information. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/keycloak.md b/platform-enterprise_docs/enterprise/configuration/authentication/keycloak.md new file mode 100644 index 000000000..6fad070e6 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/keycloak.md @@ -0,0 +1,51 @@ +--- +title: "Keycloak" +description: Configure Keycloak as an identity provider for Seqera Platform +date: "2023-04-21" +tags: [authentication, keycloak, oidc] +--- + +Configure [Keycloak](https://www.keycloak.org/) as a single sign-on (SSO) provider for Seqera Platform using OpenID Connect. + +## Prerequisites + +Before you begin, you need: + +- A Keycloak instance +- Admin access to create clients in Keycloak + +Ensure you know how to configure Keycloak clients. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#assembly-managing-clients_server_administration_guide) for more information. + +## Create a Keycloak client + +1. In **Realm settings**, verify the **Endpoints** field includes _OpenID Endpoint Configuration_. +2. Go to **Clients** and select **Create**. +3. Configure the client with protocol `openid-connect`, access type `confidential`, and redirect URI `https:///oauth/callback/oidc`. +4. In the **Credentials** tab, note the **Secret**. +5. In the **Keys** tab, set **Use JWKS URL** to `OFF`. +6. Note the issuer URL from **Realm Settings > Endpoints > OpenID Configuration** (the `issuer` value in the JSON). + +## Configure Seqera + +Add the following environment variables to your Seqera configuration: + +| Variable | Description | +| :------- | :---------- | +| `TOWER_OIDC_CLIENT` | The client ID from step 3 | +| `TOWER_OIDC_SECRET` | The secret from step 4 | +| `TOWER_OIDC_ISSUER` | The issuer URL from step 6, e.g., `https://keycloak.example.com/auth/realms/master` | + +## Restrict access + +To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: + +```yaml +tower: + auth: + oidc: + allow-list: + - "*@your-company.com" + - "specific-user@example.com" +``` + +See [User access allow list](./overview#user-access-allow-list) for more information. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/okta.md b/platform-enterprise_docs/enterprise/configuration/authentication/okta.md new file mode 100644 index 000000000..9cc68b1d5 --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/okta.md @@ -0,0 +1,57 @@ +--- +title: "Okta" +description: Configure Okta as an identity provider for Seqera Platform +date: "2023-04-21" +tags: [authentication, okta, oidc] +--- + +Configure [Okta](https://www.okta.com/) as a single sign-on (SSO) provider for Seqera Platform using OpenID Connect. + +## Prerequisites + +Before you begin, you need: + +- An Okta organization +- Administrator access to create applications + +Ensure you know how to create Okta app integrations. See Okta's documentation on [creating OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) for more information. + +## Create an Okta app integration + +1. In the **Admin Console**, go to **Applications > Applications**. +2. Select **Create App Integration**. +3. Select **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type. +4. Enter a name for the app, e.g., `Seqera`. +5. Set the sign-in redirect URI to `https:///oauth/callback/oidc`. +6. Set the sign-out redirect URI to `https:///logout`. +7. Note the **Client ID** and **Client secret** from the application settings. +8. Note the **Issuer** URL from **Sign On > OpenID Connect ID Token**. + +## Configure Seqera + +Add the following environment variables to your Seqera configuration: + +| Variable | Description | +| :------- | :---------- | +| `TOWER_OIDC_CLIENT` | The client ID from step 7 | +| `TOWER_OIDC_SECRET` | The client secret from step 7 | +| `TOWER_OIDC_ISSUER` | The issuer URL from step 8 | + +:::note +Connection strings can differ based on the issuer type. Verify the issuer URL via the Okta console. +::: + +## Restrict access + +To restrict access to specific email addresses or domains, configure an allow list in `tower.yml`: + +```yaml +tower: + auth: + oidc: + allow-list: + - "*@your-company.com" + - "specific-user@example.com" +``` + +See [User access allow list](./overview#user-access-allow-list) for more information. diff --git a/platform-enterprise_docs/enterprise/configuration/authentication/overview.md b/platform-enterprise_docs/enterprise/configuration/authentication/overview.md new file mode 100644 index 000000000..133b5921f --- /dev/null +++ b/platform-enterprise_docs/enterprise/configuration/authentication/overview.md @@ -0,0 +1,128 @@ +--- +title: "Authentication" +description: Configure authentication and identity providers for Seqera Platform +date: "2023-04-21" +tags: [authentication, configuration, sso, oidc] +--- + +Seqera Platform supports email and various OAuth providers for login authentication. + + +## Identity providers + +Configure single sign-on (SSO) login with any of the following identity providers: + +| Provider | Protocol | Configuration | +| :--------------------- | :------- | :--------------- | +| [GitHub](./github) | OAuth | `TOWER_GITHUB_*` | +| [Google](./google) | OAuth | `TOWER_GOOGLE_*` | +| [Keycloak](./keycloak) | OIDC | `TOWER_OIDC_*` | +| [Entra ID](./entra) | OIDC | `TOWER_OIDC_*` | +| [Okta](./okta) | OIDC | `TOWER_OIDC_*` | + +## OpenID Connect configuration + +:::note +You can combine different provider types (e.g., GitHub + Google + one OIDC provider). However, only one OIDC provider can be configured at a time. +::: + +For OIDC providers, configure authentication with these environment variables: + +| Variable | Description | +| :------------------ | :------------------------------------------------------------------------------------------ | +| `TOWER_OIDC_CLIENT` | The client ID provided by your authentication service | +| `TOWER_OIDC_SECRET` | The client secret provided by your authentication service | +| `TOWER_OIDC_ISSUER` | The authentication service URL to which Seqera connects to authenticate the sign-in request | + +Some providers require the full authentication service URL while others require only the SSO root domain (without the trailing sub-directories). + +In your OpenID provider settings, specify the following URL as a callback address or authorized redirect: + +``` +https:///oauth/callback/oidc +``` + +## Root users + +Root users have administrative access to all Platform resources. Configure root users by user ID or email address: + +**Environment variable** + +```env +TOWER_ROOT_USERS=1,admin@company.com +``` + +**tower.yml** + +```yaml +tower: + admin: + root-users: "1,admin@company.com" +``` + +## Disable email login + +Disable email-based (magic link) authentication when OAuth providers are configured. + +:::note +This setting only takes effect when at least one OAuth provider (GitHub, Google, or OIDC) is configured. +::: + +**Environment variable** + +```env +TOWER_AUTH_DISABLE_EMAIL=true +``` + +**tower.yml** + +```yaml +tower: + auth: + disable-email: true +``` + +## Session management + +Platform login sessions remain active as long as the application browser window remains open and active. Sessions use short-lived access tokens that are automatically refreshed via heartbeat. + +| Setting | Default | Description | +| :------------------------- | :--------- | :--------------------------------------------------------------------- | +| `access-token.expiration` | 3600s (1h) | Short-lived token, auto-refreshed via heartbeat | +| `refresh-token.expiration` | 6h | Session idle timeout — user logged out after this period of inactivity | +| `cookie-max-age` | 12h | Browser cookie lifetime (should be ≥ refresh token) | + +**tower.yml** + +```yaml +micronaut: + security: + token: + jwt: + signatures: + refresh-token: + expiration: 8h + generator: + access-token: + expiration: 3600 + refresh: + cookie: + cookie-max-age: 10h +``` + +## User access allow list + +Restrict access to specific user email addresses or domains. Allow list entries are case-insensitive. + +Replace `` with `github`, `google`, or `oidc`. Use `oidc` for any authentication service based on OpenID Connect (Okta, Entra ID, Keycloak, etc.). Include each provider separately if you configure more than one. + +**tower.yml** + +```yaml +tower: + auth: + : + allow-list: + - "*@foo.com" + - "me@bar.com" +``` From 04c91d1b3036c761beb23c3188afebb2b2f6e359 Mon Sep 17 00:00:00 2001 From: Gavin Elder Date: Mon, 22 Dec 2025 23:54:58 +0000 Subject: [PATCH 5/5] docs: refactor authentication