Managing Dependencies

Dependencies are external libraries or modules that your project relies on. Proper management of these dependencies ensures your project runs consistently across different environments.

We recommend to pin your dependencies to avoid unexpected issues when newer versions introduce breaking changes that disrupt your workflow during deployments. It ensures that your project uses specific versions that have been tested and proven to work.

JavaScript

Create a package.json file in the root of your project by running docker compose run --rm web npm init to install all your dependencies with their versions. For example:

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

Then generate a package-lock.json file by running:

docker compose run --rm web npm install

Continue installing dependencies through:

docker compose run --rm web npm install react@18.2.0 react-dom@18.2.0 --save

To avoid issues between your local environment and Divio Cloud, use docker compose to manage/install your dependencies and not your local setup.

Python

Create a requirements.in file in the root of your project and list all your dependencies with their versions. For example:

Django>=5.1,<5.2
requests

Then generate a requirements.txt file by running:

docker compose run --rm web pip-compile requirements.in

Continue installing dependencies by adding them to the requirements.in file and run pip-compile to generate the requirements.txt file.

To avoid issues between your local environment and Divio Cloud, use docker compose to manage/install your dependencies and not your local setup.

Java

Create a pom.xml file in the root of your project and list all your dependencies with their versions. For example:

<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>5.3.8</version>
  </dependency>
</dependencies>

You can also generate a pom.xml file by running:

docker compose run --rm web mvn install

Continue adding your dependencies to the pom.xml file.

To avoid issues between your local environment and Divio Cloud, use docker compose to manage/install your dependencies and not your local setup.

ASP.NET

Create a packages.config file in the root of your project and list all your dependencies with their versions. For example:

<package id="Newtonsoft.Json" version="13.0.1" />

You can also generate a packages.config file by running:

docker compose run --rm web dotnet add package Newtonsoft.Json --version 13.0.1

Continue installing dependencies through:

docker compose run --rm web dotnet add package Newtonsoft.Json --version 13.0.1

To avoid issues between your local environment and Divio Cloud, use docker compose to manage/install your dependencies and not your local setup.

PHP

Create a composer.json file in the root of your project and list all your dependencies with their versions. For example:

{
  "require": {
    "monolog/monolog": "2.3.2"
  }
}

Then generate a composer.lock file by running:

docker compose run --rm web composer install

Continue installing dependencies through:

docker compose run --rm web composer require monolog/monolog:2.3.2

To avoid issues between your local environment and Divio Cloud, use docker compose to manage/install your dependencies and not your local setup.

Ruby on Rails

Create a Gemfile file in the root of your project and list all your dependencies with their versions. For example:

gem 'rails', '6.1.4'
gem 'pg', '1.2.3'

Then generate a Gemfile.lock file by running:

docker compose run --rm web bundle install

Continue installing dependencies through:

docker compose run --rm web bundle add rails:6.1.4

To avoid issues between your local environment and Divio Cloud, use docker compose to manage/install your dependencies and not your local setup.

Go

Create a go.mod file in the root of your project and list all your dependencies with their versions. For example:

module your_module

go 1.16

require (
  github.com/gin-gonic/gin v1.7.2
)

Then generate a go.sum file by running:

docker compose run --rm web go mod tidy

Continue installing dependencies through:

docker compose run --rm web go get github.com/gin-gonic/gin@v1.7.2

To avoid issues between your local environment and Divio Cloud, use docker compose to manage/install your dependencies and not your local setup.

Developing locally

We recommend using docker compose to manage your dependencies locally and ensure consistency between your local environment and Divio Cloud. Otherwise you may run into issues where your local environment works but the deployment fails. For this, prepend all commands with: docker compose run --rm web

Checking for CDN/Package Manager Errors

Before assuming a dependency issue is on our end, always check if the problem is with the package manager or CDN itself. Sometimes, connectivity or service outages can cause errors that aren't related to our setup. Here's a list of common package managers and their status pages:

• npm (Node.js): status.npmjs.org
• PyPI (Python): status.python.org
• Maven (Java): status.maven.org
• NuGet (ASP.NET): status.nuget.org
• Composer (PHP): status.packagist.org
• RubyGems (Ruby on Rails): status.rubygems.org

Always verify that these services are operational before diving deep into troubleshooting on your side.

Why Pinning Dependencies is Important

Pinning dependencies is essential for maintaining consistency across development and production environments over time, but running your applications directly on your local machine still exposes you to the classic "works on my machine" syndrome.

Instead, consider using Docker and Docker Compose for your development and CI/CD pipelines. This approach ensures that the exact environment, including OS, dependencies, and configurations, is mirrored across all stages of development and deployment.

Divio containerizes your applications to reduce the risk of deployment issues and make it easier to reproduce any bugs or discrepancies between local development and cloud environments. Docker also provides isolation, which helps avoid conflicts between different projects on the same machine.

The Wheels Proxy

Used in legacy templates

The wheels proxy continues to be supported by Divio, but we do not recommend using it for new applications. Use our quickstart templates instead.

Divio Cloud provides a wheels proxy to cache and serve Python packages. This proxy ensures that your Python dependencies are available even if the PyPI service is down. The proxy also speeds up the installation process by caching packages locally.

Read more about Divio's wheels proxy.