Distributing TYPO3 Docker images for 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.

When deploying a TYPO3 site using Docker, your custom site package, extensions, and configuration are typically bundled into a Docker image. Before the container can be run on a production server, that image needs to be distributed to the server — usually via a container registry or manual transfer.

This guide focuses specifically on secure image distribution, which is a critical 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 and are not covered here.

Option 1: Docker Hub (private repository)

Docker Hub provides private repositories, which allow you to push and pull images 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 make sure "Private" is selected

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 offer 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.