> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment

> Configure and manage environments for your applications

## Overview

An environment is a group of applications, databases, and services running within the same Kubernetes namespace. Each environment provides isolation and organization for your services across different stages of your development lifecycle.

## Types of Environment

Qovery supports four environment modes, each designed for specific use cases:

### Production

**Critical environment** for live applications serving real users.

<Warning>
  Production environments should not be stopped or deleted by anyone without careful consideration and proper approval.
</Warning>

### Staging

**Production-like environment** for final testing before deployment. Often reflects production conditions and is critical for companies to validate changes before release.

### Development

**Working environment** for developing and testing features. Used by developers for day-to-day work, testing, and experimentation.

### Preview

**Ephemeral environment** automatically created for pull requests. Temporary environments that can be auto-deleted when no longer needed.

## Create an Environment

<Steps>
  <Step title="Access Project">
    Navigate to the project where you want to create the environment

    <img src="https://mintcdn.com/qovery/ziWdn5St6rf4bcBc/images/configuration/environment/create_environment_1.png?fit=max&auto=format&n=ziWdn5St6rf4bcBc&q=85&s=55761ac584e123af6ea83fd5266c0c8a" alt="Create Environment" width="3164" height="2070" data-path="images/configuration/environment/create_environment_1.png" />
  </Step>

  <Step title="Create Environment">
    Click the **Create Environment** button
  </Step>

  <Step title="Configure Environment">
    Specify the following parameters:

    * **Name**: A descriptive name for your environment
    * **Mode**: Select environment type (Production, Staging, Development, or Preview)
    * **Cluster**: Choose the Kubernetes cluster where the environment will run

          <img src="https://mintcdn.com/qovery/ziWdn5St6rf4bcBc/images/configuration/environment/create_environment_2.png?fit=max&auto=format&n=ziWdn5St6rf4bcBc&q=85&s=6fe3a49fde179cb31e3ab4cc6d3dabbe" alt="Create Environment Modal" width="3164" height="2070" data-path="images/configuration/environment/create_environment_2.png" />

    <Info>
      Once an environment is provisioned, the cluster assignment cannot be changed.
    </Info>
  </Step>

  <Step title="Create">
    Click **Create** to finalize the environment setup
  </Step>
</Steps>

### Adding Services

After creation, you can add services including:

* Applications
* Cronjobs
* Lifecycle jobs
* Databases

<img src="https://mintcdn.com/qovery/ziWdn5St6rf4bcBc/images/configuration/environment/create_service.png?fit=max&auto=format&n=ziWdn5St6rf4bcBc&q=85&s=6116a5860bdccdcfc24cd85e34002ea3" alt="Create Service" width="3164" height="2070" data-path="images/configuration/environment/create_service.png" />

## Environment Settings

Access environment settings to configure various aspects of your environment:

<img src="https://mintcdn.com/qovery/ziWdn5St6rf4bcBc/images/configuration/environment/environment_settings.png?fit=max&auto=format&n=ziWdn5St6rf4bcBc&q=85&s=79e333f94d5c14f0e8b63235f80197d5" alt="Environment Settings" width="3164" height="2070" data-path="images/configuration/environment/environment_settings.png" />

### General Tab

Configure basic environment properties:

* **Environment Name**: Update the environment name
* **Environment Mode**: Change between Production, Staging, Development, or Preview

<Info>
  The cluster assignment is immutable after the environment is provisioned.
</Info>

### Deployment Rules

Set policies to reduce costs and control deployments. Learn more about [deployment rules](/configuration/deployment/overview) for cost optimization.

### Deployment Pipeline

Configure the deployment pipeline to be executed when a deployment on the environment is triggered. Control how services are deployed within the environment.

Learn more about [deployment pipelines](/configuration/deployment/pipeline).

## Preview Environments

Preview Environments are temporary, isolated environments automatically created from your blueprint environment when you open a pull request. They enable you to test changes in production-like conditions before merging.

<Info>
  **Tutorial**: For a complete step-by-step tutorial on getting started with Preview Environments, including prerequisites and detailed setup instructions, see our [Getting Started with Preview Environments Tutorial](/getting-started/guides/use-cases/preview-environments).
</Info>

### What are Preview Environments?

Preview Environments solve the challenge of maintaining testing environments that accurately mirror production without manual DevOps overhead. When you open a pull request, Qovery automatically creates a clone of your production setup, allowing you to:

* **Share live changes** in code reviews beyond Git diffs
* **Generate shareable links** for stakeholder collaboration
* **Run CI tests** against high-fidelity production copies before merging

<Frame>
  <img src="https://mintcdn.com/qovery/R1k0tyd88ID8Zjqq/images/preview-environment/preview_env_flow_schema.jpg?fit=max&auto=format&n=R1k0tyd88ID8Zjqq&q=85&s=1671ea58c4ef4317b26ebefe40bf742a" alt="Preview Environment workflow diagram" width="1800" height="1642" data-path="images/preview-environment/preview_env_flow_schema.jpg" />
</Frame>

### Key Concepts

#### Blueprint Environment

A Blueprint Environment serves as the template for all your Preview Environments. It's a fully-configured, working environment that Qovery clones whenever a new pull request is created. The deployment pipeline configuration, including [skipped services](/configuration/deployment/pipeline#skipped-services), is inherited by each Preview Environment created from the Blueprint.

**Blueprint Best Practices**:

* Use a separate cluster from production for Preview Environments
* Ensure all applications and services are properly configured
* Test the Blueprint thoroughly before enabling Preview Environments
* Keep it in sync with your production configuration
* Review which services are [skipped](/configuration/deployment/pipeline#skipped-services) in the Blueprint, as Preview Environments will inherit this configuration

<Frame>
  <img src="https://mintcdn.com/qovery/R1k0tyd88ID8Zjqq/images/preview-environment/preview_env_branching.jpg?fit=max&auto=format&n=R1k0tyd88ID8Zjqq&q=85&s=1e8c1de62c3554e44c4cf8d6aa17d678" alt="Git branching strategy for Preview Environments" width="1400" height="1055" data-path="images/preview-environment/preview_env_branching.jpg" />
</Frame>

#### Base Branch

The base branch (e.g., `main` or `staging`) determines when Preview Environments are created. When you create a pull request targeting the base branch, Qovery automatically clones your Blueprint Environment.

### Quick Setup

<Steps>
  <Step title="Create Blueprint Environment">
    Clone your existing working environment and name it "blueprint"

    1. Navigate to your working environment
    2. Click **Clone Environment**
    3. Name it "blueprint" or similar
    4. Deploy and verify it works correctly
  </Step>

  <Step title="Enable Preview Environments">
    Activate the Preview Environment feature for your applications

    1. Go to Environment Settings
    2. Select the **Preview Environments** tab
    3. Toggle **Enable Preview Environments**
    4. Select which services to include

           <img src="https://mintcdn.com/qovery/ziWdn5St6rf4bcBc/images/configuration/environment/preview_environment.png?fit=max&auto=format&n=ziWdn5St6rf4bcBc&q=85&s=f67f4274188ff9cba23d0fa88646e55a" alt="Preview Environment Settings" width="3164" height="2070" data-path="images/configuration/environment/preview_environment.png" />
  </Step>

  <Step title="Configure Base Branch">
    Set the base branch for each application in your Blueprint

    1. Open each application in the Blueprint environment
    2. Go to application settings
    3. Change Git Branch to your base branch (e.g., `main` or `staging`)
    4. This ensures feature branches create isolated Preview Environments
  </Step>

  <Step title="Create a Pull Request">
    Open a PR and Qovery will automatically create a Preview Environment

    1. Create a feature branch
    2. Make your changes
    3. Open a pull request to the base branch
    4. Qovery creates a Preview Environment automatically
    5. Access the preview URL from the PR comments
  </Step>
</Steps>

### Preview Environment Workflows

Qovery supports two workflows for creating Preview Environments:

#### Automatic (On Every PR)

Qovery automatically creates a Preview Environment for every pull request targeting your base branch.

**Best for**: Teams that want maximum automation and always need to test changes

**Setup**:

1. Enable auto-preview in environment settings
2. Select services to deploy automatically
3. Configure auto-delete rules

#### Manual (On Demand)

Developers manually trigger Preview Environment creation by commenting on pull requests.

**Best for**: Teams that want to control costs or only need Preview Environments for specific PRs

**Setup**:

1. Enable preview environments in environment settings
2. Configure which services to include
3. Developers comment `/qovery preview` on PRs to trigger creation

<img src="https://mintcdn.com/qovery/8MS1YuE7IZgIf0M9/images/configuration/environment/preview_env_flow_ondemand.png?fit=max&auto=format&n=8MS1YuE7IZgIf0M9&q=85&s=e8a00f8da00560ba9f74c917e006e099" alt="Preview Environment Flow" width="648" height="847" data-path="images/configuration/environment/preview_env_flow_ondemand.png" />

### Per-Service Configuration

You have fine-grained control over which services are deployed in Preview Environments:

* **Applications**: Choose which applications to include
* **Databases**: Optionally include databases (clones or shared)
* **Services**: Select supporting services to deploy

This flexibility helps control costs and deployment times.

### Auto-Delete Functionality

Configure automatic cleanup of Preview Environments to control costs:

**Delete triggers**:

* When PR is merged
* When PR is closed without merging
* After specified period of inactivity
* Manual deletion via CLI or Console

**Cost optimization**: Preview Environments are typically deleted within minutes of PR closure, preventing unnecessary infrastructure costs.

### Advanced Features

<AccordionGroup>
  <Accordion title="Database Seeding" icon="seedling">
    Populate Preview Environment databases with test data using Lifecycle Jobs.

    * Run SQL scripts on environment startup
    * Seed databases with production-like data
    * Reset data between deployments

    [Learn more about database seeding](/getting-started/guides/others/database-seeding-lifecycle-job)
  </Accordion>

  <Accordion title="CI/CD Integration" icon="rotate">
    Integrate Preview Environments with your CI/CD pipeline for automated testing.

    * Trigger tests automatically when Preview Environment is ready
    * Run E2E tests against preview URLs
    * Post results back to pull requests

    [See CI/CD integration examples](/configuration/integrations/ci-cd/github-actions)
  </Accordion>

  <Accordion title="Custom Domains" icon="globe">
    Configure custom domains for Preview Environments.

    * Use wildcard DNS (e.g., `*.preview.yourdomain.com`)
    * Automatic SSL certificates
    * Shareable URLs for stakeholders
  </Accordion>

  <Accordion title="Resource Management" icon="server">
    Control resources to optimize costs for Preview Environments.

    * Use smaller instance sizes than production
    * Set auto-stop rules for inactive environments
    * Configure memory and CPU limits per service
  </Accordion>
</AccordionGroup>

### Common Use Cases

<CardGroup cols={2}>
  <Card title="Feature Development" icon="code">
    Test new features in isolation before merging to main branch
  </Card>

  <Card title="Bug Fixes" icon="bug">
    Verify bug fixes work correctly in production-like environment
  </Card>

  <Card title="Stakeholder Review" icon="users">
    Share live previews with product managers, designers, and clients
  </Card>

  <Card title="E2E Testing" icon="flask">
    Run automated tests against realistic environments before deployment
  </Card>
</CardGroup>

### Best Practices

<AccordionGroup>
  <Accordion title="Blueprint Maintenance" icon="wrench">
    * Keep your Blueprint environment up-to-date with production configuration
    * Test Blueprint deployments regularly to catch issues early
    * Document any special configuration requirements
    * Use environment variables for environment-specific values
  </Accordion>

  <Accordion title="Cost Optimization" icon="dollar-sign">
    * Enable auto-delete for merged/closed PRs
    * Use smaller instance sizes for Preview Environments
    * Set up deployment rules to stop inactive environments
    * Only include necessary services in previews
    * Use shared databases instead of cloning when appropriate
  </Accordion>

  <Accordion title="Security" icon="shield">
    * Don't use production secrets in Preview Environments
    * Restrict access to preview URLs if needed
    * Use separate clusters for production and previews
    * Regularly audit and clean up orphaned environments
  </Accordion>

  <Accordion title="Performance" icon="bolt">
    * Optimize Docker images to reduce deployment time
    * Use caching strategies for dependencies
    * Consider lazy-loading large databases
    * Parallel deploy services when possible
  </Accordion>
</AccordionGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Preview Environment Not Created" icon="circle-xmark">
    **Possible causes**:

    * Preview Environments not enabled in settings
    * PR not targeting the configured base branch
    * Blueprint environment has errors
    * Insufficient cluster resources

    **Solutions**:

    * Verify Preview Environment settings are enabled
    * Check that PR targets correct base branch
    * Ensure Blueprint environment deploys successfully
    * Review cluster capacity and quotas
  </Accordion>

  <Accordion title="Deployment Failures" icon="triangle-exclamation">
    **Possible causes**:

    * Blueprint environment configuration errors
    * Missing environment variables
    * Resource constraints
    * Container image build failures

    **Solutions**:

    * Test Blueprint environment deployment manually
    * Review application logs for errors
    * Verify all required environment variables are set
    * Check container image build logs
  </Accordion>

  <Accordion title="Preview Environment Not Deleted" icon="trash">
    **Possible causes**:

    * Auto-delete not configured
    * Webhook not triggered
    * Manual intervention required

    **Solutions**:

    * Check auto-delete settings
    * Manually delete via Console or CLI
    * Review webhook configuration in Git provider
  </Accordion>
</AccordionGroup>

## Clone Environment

Duplicate an existing environment to quickly create a copy across projects or clusters:

<img src="https://mintcdn.com/qovery/ziWdn5St6rf4bcBc/images/configuration/environment/clone_environment.png?fit=max&auto=format&n=ziWdn5St6rf4bcBc&q=85&s=ec9787f239edf2449829bc4dc0f84a35" alt="Clone Environment" width="3164" height="2070" data-path="images/configuration/environment/clone_environment.png" />

<Steps>
  <Step title="Select Environment">
    Go to the environment you want to clone
  </Step>

  <Step title="Clone">
    Click the **Clone** button in environment settings
  </Step>

  <Step title="Configure Clone">
    Specify:

    * New environment name
    * Target project (can be different)
    * Target cluster (can be different)
    * Which services to include

          <img src="https://mintcdn.com/qovery/ziWdn5St6rf4bcBc/images/configuration/environment/clone_environment_modal.png?fit=max&auto=format&n=ziWdn5St6rf4bcBc&q=85&s=cac12909c6a3489a2181a669a765fc78" alt="Clone Environment Modal" width="3164" height="2070" data-path="images/configuration/environment/clone_environment_modal.png" />
  </Step>

  <Step title="Create Clone">
    Click **Clone Environment** to create the copy
  </Step>
</Steps>

<Info>
  Cloning excludes:

  * Custom domains
  * Certain built-in environment variables

  Cloning preserves:

  * [Deployment pipeline](/configuration/deployment/pipeline) stage configuration
  * [Skipped services](/configuration/deployment/pipeline#skipped-services) status — services that were skipped in the source environment will also be skipped in the cloned environment
</Info>

## Deployment & Deletion

### Deploying an Environment

Deploy all services in an environment through the Qovery Console or CLI. See [deployment management](/configuration/deployment/overview) for details.

### Deleting an Environment

<Warning>
  Deleting an environment is a **permanent operation**. All services, databases, and data will be irreversibly deleted.
</Warning>

Before deleting:

1. Backup important data
2. Stop all services
3. Verify you're deleting the correct environment

## Related Topics

<CardGroup cols={2}>
  <Card title="Project" href="/configuration/project">
    Learn about project configuration
  </Card>

  <Card title="Applications" href="/configuration/application">
    Configure applications within environments
  </Card>

  <Card title="Databases" href="/configuration/database">
    Add databases to your environments
  </Card>

  <Card title="Ephemeral Environments" href="/getting-started/guides/use-cases/ephemeral-environment">
    Learn about preview environments and CI/CD integration
  </Card>

  <Card title="Deployment Pipeline" href="/configuration/deployment/pipeline">
    Configure deployment order and strategies
  </Card>

  <Card title="Terraform Exporter" href="/terraform-provider/exporter">
    Export environment as Terraform code
  </Card>
</CardGroup>