Devcontainer Setup

Overview

Zammad provides a pre-configured development container (devcontainer) for a ready-to-use development environment.

This is the recommended way to set up your environment, as it eliminates the need to manually install and configure dependencies.

Stack options

• Default
• With Mailserver (for local email testing)
• With Ollama (for local AI playground)
• With Selenium (for integration tests)

Prerequisites

• VS Code with the Dev Containers extension (or other compatible editors / terminals).
• Docker Desktop or Docker CLI.

Ensure Docker has at least 8 GB of memory and sufficient CPU allocated. You can configure this in Docker Desktop's settings (Settings > Resources).

Build and Launch the Container

• Clone the Zammad repository (if you haven't already).
• Open the root of the Zammad checkout in VS Code. A pop-up will appear in the bottom-right corner: "Reopen in Container". Click it.
• VS Code will now build the devcontainer.

Accessing Zammad

Once the build is complete, the container will automatically:

• Start all required services (PostgreSQL, Redis, Elasticsearch).
• Initialize and seed the database.

Open a new terminal window and start the development server:

dev

Access the app at https://localhost:3000

The first run may take a few minutes while Rails compiles assets. You may see a blank browser window until this is complete.

Default Credentials

Username / Email: [email protected]
Password: test

Customizing Your Development Environment

You can personalize your Zammad development container using your own dotfiles.

Dev Container Settings

Before using dotfiles, configure the following settings in VS Code:

• dotfiles.installCommand - Command provided by your repository to deploy the dotfiles (for example install.sh)

• dotfiles.repository - Git repository to clone

  These settings are only available when the folder is opened locally.

The devcontainer comes with oh-my-zsh pre-installed, so you can extend it with your own themes, aliases, and plugins.

[!TIP] When setting this up for the first time, a container rebuild is required.

Known Issues

Rebase Issues on Mac

When working inside the devcontainer on mac, you might encounter problems rebasing branches. This is due to a known issue between Docker Desktop and Git file stat checks.

You can resolve this by configuring Git to perform minimal file stat checking:

git config set --system core.checkStat minimal

Note that this setting will not persist between container rebuilds, so you can also place it in your local .gitconfig first:

[core]
checkStat = minimal

What's Next?

Now that your development environment is up and running, the next step is to get familiar with the Zammad development workflow.

Read the Development Workflow guide for details on testing, debugging, and contributing code.