Skip to main content
Ona fully supports Development Containers, allowing you to standardize development environments across your team. Define your setup in a devcontainer.json file to ensure consistent tools, dependencies, and configurations for all developers.

​
Benefits

Using Dev Containers with Ona provides several advantages:
  • Standardized environments across all team members
  • Consistent tooling with precisely defined dependency versions
  • Isolated Linux VM environments, even when running locally
  • Support for both single and multi-container development setups
  • Version-controlled configuration that lives with your codebase
  • Integration with VS Code and other supported editors
  • Separation of development environment from local machine configuration

​
Configuration

​
File Location

Place your devcontainer.json file in one of these standard locations:
  • .devcontainer/devcontainer.json
  • .devcontainer.json

​
Basic Configuration Example

{
	"name": "My Project",
	"image": "mcr.microsoft.com/devcontainers/universal:4.0.1-noble",
	"features": {
		"ghcr.io/devcontainers/features/docker-in-docker:2": {}
	},
	"customizations": {
		"vscode": {
			"extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
			"settings": {
				"editor.formatOnSave": true
			}
		},
		"jetbrains": {
			"plugins": ["com.wix.eslint", "intellij.prettierJS"]
		}
	},
	"forwardPorts": [3000, 8080]
}
This configuration:
  • Uses the Universal image with common languages and tools pre-installed
  • Adds Docker-in-Docker support
  • Adds Node.js LTS
  • Includes ESLint and Prettier VS Code extensions
  • Installs the ESLint & PrettierJS plugin for JetBrains IDEs
  • Configures auto-formatting on save
  • Forwards ports 3000 and 8080

​
Multiple Dev Container configurations

You can manage multiple Dev Container configurations using Ona projects. This allows you to define different environments for:
  • Different branches or repositories
  • Various development scenarios
  • Specialized tasks requiring specific tools

​
Known limitations

When using Dev Containers with Ona, be aware of these limitations:
  • Platform-specific features may not work with Ona Desktop
  • Conflicting features can cause build failures (Ona will display an error message)
  • Some Dev Container commands might behave differently in Ona’s environment
  • When build errors occur, recovery mode is engaged, requiring manual intervention
Microsoft provides well-maintained Dev Container base images for popular development stacks:
  • mcr.microsoft.com/devcontainers/universal:4.0.1-noble - Full-featured image with common languages and tools
  • mcr.microsoft.com/devcontainers/javascript-node - Node.js development
  • mcr.microsoft.com/devcontainers/python - Python development
  • mcr.microsoft.com/devcontainers/dotnet - .NET development
  • mcr.microsoft.com/devcontainers/java - Java development
  • mcr.microsoft.com/devcontainers/go - Go development
  • mcr.microsoft.com/devcontainers/base:ubuntu - Minimal image

​
Advanced configuration

​
Multi-Container Development

For more complex setups, you can define multiple containers using Docker Compose. devcontainer.json: 
{
	"name": "Multi-container App",
	"dockerComposeFile": "docker-compose.yml",
	"service": "app",
	"workspaceFolder": "/workspace",
	"customizations": {
		"vscode": {
			"extensions": ["ms-azuretools.vscode-docker"]
		}
	}
}
docker-compose.yml: 
version: "3.8"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspace:cached
    network_mode: host
    command: sleep infinity

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    network_mode: host
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_dev
Required: Set network_mode: host on all services. Without this, services attempt to bridge networks, which can lock you out of your dev container with no way to recover except deleting the environment.

​
Adding Custom Features

Dev Container Features are self-contained, shareable units of installation code and configuration that let you quickly add tooling, runtimes, or libraries to your development container. You can add features to your Dev Container by adding them to the features section of your devcontainer.json file: 
{
	"features": {
		"ghcr.io/devcontainers/features/docker-in-docker:2": {},
		"ghcr.io/devcontainers/features/github-cli:1": {}
	}
}
Ona works well with many Dev Container Features, especially official ones that are designed with remote development environments in mind. Linux-based runners generally provide best compatibility with most Dev Container Features. Here’s what you should know:
  • Community-supported features might require additional testing, as they may have been developed without specific consideration for compatibility.
  • Feature behavior can vary depending on base images, other installed features, and specific configurations in your setup.

​
Troubleshooting

If your Dev Container fails to build:
  1. Check the Ona console for specific error messages
  2. Ensure image versions are correctly specified
  3. Try rebuilding in recovery mode to debug the issue

​
Next steps