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

# Customize your Astro project Dockerfile

> Customize your Astro project Dockerfile to use a different distribution, add CA certificates, or run additional build-time arguments.

By default, the Astro project Dockerfile only includes a `FROM` statement that specifies your Astro Runtime version. However, you can extend your Dockerfile to use a different distribution or run additional buildtime arguments. Use this document to learn which Dockerfile customizations are supported both locally and on Astro.

## Prerequisites

* An [Astro project](/docs/cli/v1.46/develop-project#create-an-astro-project)

## Use an alternative Astro Runtime distribution

Starting with Astro Runtime 9, each version of Astro Runtime has a separate distribution for each currently supported Python version. Use an alternative Python distribution if any of your dependencies require a Python version other than the [default Runtime Python version](/docs/runtime/runtime-image-architecture#python-versioning).

<Info>Replace `<registry-url>` with the Docker registry URL. Airflow 2.x-based Runtime versions and Airflow 3.x-based Runtime versions have different registry URLs. See [Docker Registry URLs](/docs/runtime/runtime-image-architecture#container-registry-urls) for information on which URL to pull from.</Info>

To use a specific Python distribution, update the first line in your Astro project `Dockerfile` to reference the required distribution:

```text wrap theme={null}
FROM <registry-url><runtime-version>-python-<python-version>
```

For example, to use Python 3.10 with Astro Runtime version 9.0.0, you update the first line of your Dockerfile to the following:

```text wrap theme={null}
FROM <registry-url>9.0.0-python-3.10
```

## Run commands on build

To run additional commands as your Astro project is built into a Docker image, add them to your `Dockerfile` as `RUN` commands. These commands run as the last step in the image build process.

<Info>Replace `<registry-url>` with the Docker registry URL. Airflow 2.x-based Runtime versions and Airflow 3.x-based Runtime versions have different registry URLs. See [Docker Registry URLs](/docs/runtime/runtime-image-architecture#container-registry-urls) for information on which URL to pull from.</Info>

For example, if you want to run `ls` when your image builds, your `Dockerfile` would look like this:

```text wrap theme={null}
FROM <registry-url>3.1-5
RUN ls
```

This is supported both on Astro and in the context of local development.

## Add a CA certificate to an Astro Runtime image

If you need your Astro Deployment to communicate securely with a remote service using a certificate signed by an untrusted or internal certificate authority (CA), you need to add the CA certificate to the trust store inside your Astro project's Docker image.

<Info>Replace `<registry-url>` with the Docker registry URL. Airflow 2.x-based Runtime versions and Airflow 3.x-based Runtime versions have different registry URLs. See [Docker Registry URLs](/docs/runtime/runtime-image-architecture#container-registry-urls) for information on which URL to pull from.</Info>

Whether you need the `-base` Runtime image depends on when your CA certificate needs to be trusted.

<Info>The Red Hat UBI tag suffix depends on your Runtime version: use `-ubi` for Runtime versions built on Airflow 3.2 or later, or `-ubi9` for versions built on Airflow 3.1 or earlier. See [Operating system variant images](/docs/runtime/runtime-image-architecture#operating-system-variant-images) for more information.</Info>

### Add a CA certificate that isn't needed for package installation

If your organization's packages install without needing the CA certificate (for example, the certificate is only required for your Dag code to reach an internal service at runtime), add the certificate after the default Runtime image's automatic package installation:

<Tabs>
  <Tab title="Debian">
    ```docker wrap theme={null}
    FROM <registry-url><runtime-version>

    # Switch to root for setup
    USER root

    # Add internal CA certificate
    COPY <internal-ca.crt> /usr/local/share/ca-certificates/<internal-ca.crt>
    RUN update-ca-certificates

    # Switch back to astro user
    USER astro
    ```
  </Tab>

  <Tab title="Red Hat UBI">
    ```docker wrap theme={null}
    FROM <registry-url><runtime-version>-ubi

    # Switch to root for setup
    USER root

    # Add internal CA certificate
    COPY <internal-ca.crt> /etc/pki/ca-trust/source/anchors/<internal-ca.crt>
    RUN update-ca-trust extract

    # Switch back to astro user
    USER astro
    ```
  </Tab>
</Tabs>

### Add a CA certificate needed for package installation

If your organization's system or Python packages need the CA certificate to install (for example, packages come from an internal mirror behind the same CA), add the certificate to the `-base` Runtime image before installing packages:

<Tabs>
  <Tab title="Debian">
    ```docker wrap theme={null}
    # Use the base Astro Runtime image so we can setup our CA cert before installing any packages
    FROM <registry-url><runtime-version>-base

    # Switch to root for setup
    USER root

    # Add internal CA certificate
    COPY <internal-ca.crt> /usr/local/share/ca-certificates/<internal-ca.crt>
    RUN update-ca-certificates

    # Install system packages if listed in packages.txt
    COPY packages.txt .
    RUN /usr/local/bin/install-system-packages

    # Install Python dependencies
    COPY requirements.txt .
    RUN /usr/local/bin/install-python-dependencies

    # Switch back to astro user
    USER astro

    # Copy project into image
    COPY --chown=astro:0 . .
    ```
  </Tab>

  <Tab title="Red Hat UBI">
    ```docker wrap theme={null}
    # Use the base Astro Runtime image so we can setup our CA cert before installing any packages
    FROM <registry-url><runtime-version>-ubi-base

    # Switch to root for setup
    USER root

    # Add internal CA certificate
    COPY <internal-ca.crt> /etc/pki/ca-trust/source/anchors/<internal-ca.crt>
    RUN update-ca-trust extract

    # Install system packages if listed in packages.txt
    COPY packages.txt .
    RUN /usr/local/bin/install-system-packages

    # Install Python dependencies
    COPY requirements.txt .
    RUN /usr/local/bin/install-python-dependencies

    # Switch back to astro user
    USER astro

    # Copy project into image
    COPY --chown=astro:0 . .
    ```
  </Tab>
</Tabs>

<Info>When using a base image, make sure to install the system-level and Python packages.</Info>

(Optional) Add additional `COPY` statements before the `RUN update-ca-certificates` or `RUN update-ca-trust extract` stanza for each CA certificate your organization is using for external access.

[Restart your local environment](/docs/cli/v1.46/run-airflow-locally#restart-a-local-airflow-environment) or deploy to Astro. See [Deploy code](/docs/astro/deploy-code).