Distributing TYPO3 Docker images during deployment

Warning

This section is experimental and under active development. Content is incomplete and may change as best practices evolve.

Want to help improve this section? TYPO3 documentation contributions are welcome! If you have deployment experience, examples, or corrections, please consider submitting a pull request or opening an issue on GitHub.

After you have created your Docker image (typically by bundling your custom site package, extensions, and configuration into the image) it then needs to be distributed to the production server. This can be done via a container registry or by manual transfer.

Table of contents

Choosing a secure Docker image distribution hub

This guide focuses on secure image distribution, which is an important step in the overall deployment process. Running a container and configuring a production environment (e.g. web server, database, volumes) are considered part of full deployment rather than just distribution and are not covered here.

Option 1: Docker Hub (private repository)

Docker Hub provides private repositories where images can be pushed and pulled without exposing them publicly.

To ensure your TYPO3 Docker image remains private, follow these steps:

Create a private repository using the Docker Hub web interface:
1. Visit https://hub.docker.com/repositories
2. Click "Create Repository"
3. Set the name (e.g. your-image) and select "Private"

Log in to Docker Hub, tag and push your image

docker login
docker tag your-image yourusername/your-image:tag
docker push yourusername/your-image:tag

Note: Free Docker Hub accounts allow only a limited number of private repositories. A paid plan may be required for production use.

Option 2: GitHub Container Registry (GHCR)

If your TYPO3 project's source code is stored in a GitHub repository, you can use the GitHub Container Registry (ghcr.io) to securely store Docker images.

Steps to distribute a TYPO3 image via GHCR:

Authenticate using a GitHub personal access token.
```
# echo YOUR_GITHUB_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
```
Copied!
Replace:
- YOUR_GITHUB_PAT with your personal access token
- YOUR_GITHUB_USERNAME with your GitHub username

Tag and push your image

# Tag your Docker image:
docker tag your-image ghcr.io/yourusername/your-image:tag

#Push the image
docker push ghcr.io/yourusername/your-image:tag

Tip: GHCR integrates well with GitHub Actions for CI/CD pipelines.

Option 3: GitLab Container Registry

If your TYPO3 project's source code is managed in GitLab, you can use the GitLab Container Registry to store Docker images alongside your project.

This registry is built into GitLab and integrates with GitLab CI/CD, allowing you to build, tag, and push images during your deployment pipeline.

Steps to distribute a TYPO3 image via GitLab Registry:

# Authenticate with GitLab
docker login registry.gitlab.com

# Tag your image using the GitLab project namespace
docker tag your-image registry.gitlab.com/your-namespace/your-project/your-image:tag

# Push the image
docker push registry.gitlab.com/your-namespace/your-project/your-image:tag

Note: You can manage image visibility and permissions through your GitLab project settings. This approach is ideal for teams already using GitLab as part of their development and deployment process.

Option 4: Self-hosted Docker registry

Running your own Docker registry gives you full control over where and how images are stored and accessed.

# Start a local registry
docker run -d -p 5000:5000 --name registry registry:2

# Tag and push your image
docker tag your-image localhost:5000/your-image
docker push localhost:5000/your-image

Note: For production use, configure SSL encryption and authentication.

Option 5: Cloud provider registries

If you are deploying TYPO3 to a major cloud provider, consider using their managed container registries:

Amazon ECR (Elastic Container Registry)
Google Artifact Registry
Azure Container Registry

These registries provide high security, scalability, and tight integration with their respective cloud services and IAM systems.

Summary: Choosing the right distribution method

TYPO3 Docker images must be securely transferred to the target environment before they can be deployed and run. This guide outlines secure and practical methods for distributing your TYPO3 image.

Choose the method that best fits your infrastructure, compliance needs, and workflow. All the methods described here are compatible with TYPO3 projects and can be part of modern DevOps pipelines.

Automate building and tagging of Docker images in CI/CD pipelines

It is common practice to build, tag, and distribute Docker images in a CI/CD pipeline. The tools used for this (such as GitHub Actions and GitLab CI) and the general principles are similar across platforms.