build-process-and-dockerignore

3 min read Updated 0 seconds ago

Build process and .dockerignore

When you deploy an application, Ploi Cloud builds a container image from your repository. This process uses a build system that clones your code and packages it into a container image. Understanding how this works helps you optimize build times and control what files are included in your deployments.

How the build process works

The build process follows these steps:

  1. Your repository is cloned into a temporary build environment
  2. A custom Dockerfile is generated based on your application type and settings
  3. The cloned repository directory becomes the build context within the build container
  4. Your application files are copied into the container image
  5. Build commands run to install dependencies and compile assets
  6. The final image is pushed to the container registry

Generated Dockerfile

Ploi Cloud automatically generates a Dockerfile for your application based on your application type (Laravel, Node.js, WordPress, etc.) and configuration settings. This Dockerfile is created server-side and injected into the build process - you don't need to include a Dockerfile in your repository.

Understanding .dockerignore

The .dockerignore file tells the build process which files to exclude when copying your application into the container image. This is important for:

  • Reducing image size by excluding unnecessary files
  • Improving build speed by copying fewer files
  • Preventing sensitive files from being included in the image
  • Avoiding conflicts with files generated during the build

Creating a .dockerignore file

Create a file named .dockerignore in your repository root and commit it to your Git repository. This file will be respected during each build. The syntax is similar to .gitignore:

# Dependencies installed during build
node_modules/
vendor/

# Version control
.git/
.gitignore

# Environment files
.env
.env.local
.env.*.local

# IDE and OS files
.idea/
.vscode/
*.swp
.DS_Store
Thumbs.db

# Build artifacts
dist/
build/
*.log

# Development files
docker-compose.yml
Dockerfile
.dockerignore

# Documentation
docs/
README.md
*.md

# Tests
tests/
test/
*.test.js
*.spec.js

Best practices for .dockerignore

Always exclude these files

  • Version control files (.git/) - Already cloned, not needed in the image
  • Environment files (.env) - Use platform secrets instead
  • Dependencies folders (node_modules/, vendor/) - Installed fresh during build
  • IDE configuration (.idea/, .vscode/) - Development-only files

Consider excluding

  • Documentation - Usually not needed at runtime
  • Test files - Only needed during development
  • Build artifacts - Generated during the build process
  • Large media files - Consider using object storage instead

Note: The patterns above use trailing slashes (e.g., node_modules/) to match directories anywhere in your repository. You can also use absolute paths from the repository root (e.g., /node_modules) to match only in the root directory.

Impact on build performance

A well-configured .dockerignore file can significantly improve build times:

  • Excluding node_modules/ can reduce the build context by hundreds of megabytes
  • Excluding .git/ removes repository history from the build
  • Fewer files to process means faster image layer creation

Troubleshooting

If files are missing in your deployed application:

  1. Check your .dockerignore file for overly broad patterns
  2. Remember that patterns are relative to the repository root
  3. Use ! to include files that would otherwise be excluded

Example of including a specific file while excluding a directory:

# Exclude all markdown files
*.md

# But include the changelog
!CHANGELOG.md