Defining Build Context

Overview

The Build Context field specifies the directory used during the build process. Proper configuration ensures that all necessary files and resources are accessible. This guide provides details on configuring the Build Context for different builders.

---

Default Behavior

• Default Setting: / (root directory)
• Fallback: If no Dockerfile is found, CloudStation defaults to the Nixpacks builder.
• When to Update: If your project has a special directory structure or specific build requirements.

---

Configuring Build Context

For Docker Builder

Project Root

• Use Case: When all necessary files (including the Dockerfile) are in the root directory.
• Example Project Structure:

  /
  ├── app/
  ├── config/
  ├── Dockerfile
  └── src/
• Set Build Context to: /

Subdirectory with Dockerfile

• Use Case: When the Dockerfile is inside a subdirectory.
• Example Project Structure:

  /
  ├── app/
  ├── config/
  ├── docker/
  │   └── Dockerfile
  └── src/
• Set Build Context to: /docker

---

For Nixpacks Builder

Project Root

• Use Case: When the root directory contains all necessary files.
• Example Project Structure:

  /
  ├── app/
  ├── config/
  └── src/
• Set Build Context to: /

Subdirectory with Build Configurations

• Use Case: When build configurations are inside a subdirectory.
• Example Project Structure:

  /
  ├── app/
  ├── config/
  ├── build/
  │   └── build.config
  └── src/
• Set Build Context to: /build

---

Common Use Cases

Frontend Applications

Single Page Application (SPA) with Docker Builder

• Project Structure:

  /
  ├── public/
  ├── src/
  ├── Dockerfile
  └── package.json
• Set Build Context to: /

SPA with Nixpacks Builder

• Project Structure:

  /
  ├── public/
  ├── src/
  └── package.json
• Set Build Context to: /

---

Backend Applications

Node.js Backend with Docker Builder

• Project Structure:

  /
  ├── src/
  ├── Dockerfile
  └── package.json
• Set Build Context to: /

Node.js Backend with Nixpacks Builder

• Project Structure:

  /
  ├── src/
  └── package.json
• Set Build Context to: /

---

Mono-repo with Multiple Services

Separate Dockerfiles for Each Service

• Project Structure:

  /
  ├── service1/
  │   ├── src/
  │   ├── Dockerfile
  │   └── package.json
  ├── service2/
  │   ├── src/
  │   ├── Dockerfile
  │   └── package.json
  └── common/
• Build Context for Service 1: /service1
• Build Context for Service 2: /service2

Mono-repo with Nixpacks

• Project Structure:

  /
  ├── service1/
  │   ├── src/
  │   └── package.json
  ├── service2/
  │   ├── src/
  │   └── package.json
  └── common/
• Build Context for Service 1: /service1
• Build Context for Service 2: /service2

---

Using Multiple Dockerfiles

Backend Service with Separate Dockerfiles for Development and Production

• Project Structure:

  /
  ├── src/
  ├── Dockerfile.dev
  ├── Dockerfile.prod
  └── package.json
• Build Context for Development: /Dockerfile.dev
• Build Context for Production: /Dockerfile.prod

---

Troubleshooting

File Not Found

• Issue: The build process cannot find necessary files.
• Solution: Verify the specified Build Context path relative to the project root.

Build Failures

• Issue: The build fails due to missing dependencies or incorrect directory structures.
• Solution: Check the build configuration and ensure all required files are included in the context directory.

By following these guidelines, you can configure the Build Context effectively, ensuring smooth and efficient builds for your applications using Docker or Nixpacks.

---

For further details, refer to the CloudStation documentation.