Docker Compose

Astro Theme Pure provides Docker Compose workflows for development, building, previewing and content creation in an isolated Bun container. This allows you to perform these workflows inside Docker without installing Bun or its dependencies or running the tooling directly on your host.

Requirements#

• Docker Desktop ↗ with Docker Compose ↗ support.

Verify your installation:

docker --version
docker compose version

How it works#

The included Docker environment uses:

• Bun via the official oven/bun:debian image
• A shared Docker image built from the repository Dockerfile
• Compose profiles to run specific workflows
• Named Docker volumes for build artifacts and dependencies

The Docker image:

• Installs project dependencies with bun install --frozen-lockfile
• Disables Astro telemetry
• Exposes port 4321
• Uses /web as the working directory

All services reuse the same image and only start when the corresponding profile is selected.

Available profiles#

Each workflow is exposed through a Docker Compose profile. Select the profile corresponding to the task you want to perform:

Building for production#

Generate a production build:

docker compose --profile build up --build

The build process:

1. Runs bun run build
2. Creates the Astro production output inside the container
3. Copies the generated files into your local ./dist directory

After the build completes, the generated site is available in:

./dist

The build container exits automatically when finished.

Rebuilding the Docker image#

The --build flag forces Docker Compose to rebuild the image before starting services.

Use it when:

• Updating project dependencies
• Modifying package.json
• Changing the Dockerfile
• Switching to a branch with dependency changes

Example:

docker compose --profile dev up --build

Development#

Start the Astro development server:

docker compose --profile dev up --build

The site will be available at:

http://localhost:4321

Hot reloading#

Your project directory is mounted directly into the container:

- .:/web

This means changes to source files are immediately visible inside the container, allowing Astro’s development server to hot reload automatically.

Project dependencies are stored in a dedicated Docker volume:

- node_modules:/web/node_modules

This avoids conflicts between container-managed dependencies and any local environment.

To stop the development server, press Ctrl + C.

Previewing a production build#

To build and serve the production output:

docker compose --profile preview up --build

The preview workflow:

1. Executes the build service
2. Shares the generated files through a Docker volume
3. Starts Astro Preview

The production preview is available at:

http://localhost:4321

This is useful for verifying behavior closer to a production deployment than the development server.

Creating an article#

Astro Theme Pure provides a command for scaffolding new articles that can be run without installing dependencies locally.

Create a new article:

docker compose --profile new run --rm new

This executes:

bun run pure new

The container mounts only the content directory:

- ./src/content:/web/src/content

Any generated content is written directly into your project.

The --rm flag automatically removes the temporary container after the command completes.

Cleaning up#

Stop containers and remove Compose resources:

docker compose down

Remove associated volumes as well:

docker compose down --volumes

This removes cached build output and installed dependencies stored in Docker volumes.