Devenv
Imagine devenv to function as a dependency manager for the services and packages that you need to run your application for local development or even in a CI/CD context.
Similar to other package managers, devenv lets you describe what your environment should look like and locks dependencies to a specific version to help you compose a reproducible setup.
Devenv not only lets you choose from and install different versions of binaries (e.g., PHP, Node, npm), but it also allows you to configure and run services (like MySQL, Redis, OpenSearch). The binaries and states of the services are stored on a per-project level.
The main difference to other tools like Docker or a VM is that it neither uses containerization nor virtualization techniques. Instead, the services run natively on your machine.
As devenv is built on top of Nix, first install Nix with the following command based on your OS:
macOS
Linux
Windows (WSL2)
Docker
sh <(curl -L https://nixos.org/nix/install)
sh <(curl -L https://nixos.org/nix/install) --daemon
sh <(curl -L https://nixos.org/nix/install) --no-daemon
docker run -it nixos/nix
nix-env -iA cachix -f https://cachix.org/api/v1/install
Before installing devenv, instruct Cachix to use the devenv cache:
cachix use devenv
The first time you run
cachix use, you will be prompted a warning that you are not a trusted user.This user doesn't have permissions to configure binary caches.
You can either:
a) ...
b) ...
When you encounter the above message, run:
echo "trusted-users = root ${USER}" | sudo tee -a /etc/nix/nix.conf && sudo pkill nix-daemon
Finally, install devenv:
nix-env -if https://github.com/cachix/devenv/tarball/v0.5
Before booting up your development environment, configure Cachix to use Shopware's cache:
cachix use shopware
By default,
shopware/platform uses unfree software like Blackfire. To be able to use unfree software, you have to allow it:mkdir -p ~/.config/nixpkgs
echo '{ allowUnfree = true; }' > ~/.config/nixpkgs/config.nix
You can find the whole installation guide for devenv in their official documentation:
Depending on whether you want to set up a fresh Shopware project or contribute to the Shopware core, choose between:
Symfony Flex
shopware/platform (Contribute)
If you are already using Symfony Flex, you require a Composer package to get a basic devenv configuration:
composer require devenv
This will create a basic
devenv.nix file to enable devenv support for Shopware.git clone [email protected]:shopware/platform.git
Since the environment is described via a
devenv.nix file committed to version control, you can now boot up the environment:devenv up
Make sure that the ports for the services are not already in use, or else the command will fail.
Ensure to change your
.env file to have the database connect using localhost's IP address instead of the default MySQL socket:<PROJECT_ROOT>/.env
DATABASE_URL="mysql://shopware:[email protected]:3306/shopware?sslmode=disable&charset=utf8mb4"
With a new terminal, go to the project directory and run the following command to launch a devenv shell. This shell includes all needed programs (php, composer, npm, node, etc.), to initialize Shopware:
devenv shell
In the devenv shell, run the following command to initialize Shopware:
composer setup
If you wish to switch between multiple development environments which use devenv seamlessly, we recommend installing direnv.
When you enter a project directory using devenv, direnv will automatically activate the environment for you. This means that you can use the binaries without having to run
devenv shell manually, though you still have to run devenv up to start all services.First, install direnv:
macOS
Ubuntu
Other
The preferred way to install direnv on macOS is using Homebrew:
brew install direnv
apt install direnv
Afterwards, add the following hook to your shell:
Bash
Zsh
Fish
Other
~/.bashrc
eval "$(direnv hook bash)"
~/.zshrc
eval "$(direnv hook zsh)"
~/.config/fish/config.fish
direnv hook fish | source
After you change into a project directory using devenv for the first time, you need to allow direnv to load the environment:
direnv allow
Here is an overview of services Shopware provides by default and how you can access them:
Service | Access |
|---|---|
MySQL | mysql://shopware:[email protected]:3306 |
Caddy | |
Adminer | |
Mailhog (SMTP) | smtp://127.0.0.1:1025 |
Mailhog (Web UI) |
To customize the predefined services to match your needs, e.g., changing the virtual host, database name, or environment variables, you can create
devenv.local.nix to override the service definitions. It also allows you to add and configure additional services you might require for your local development.<PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:
{
# Disable a service
services.adminer.enable = false;
# Use a custom virtual host
services.caddy.virtualHosts."http://shopware.swag" = {
extraConfig = ''
root * public
php_fastcgi unix/${config.languages.php.fpm.pools.web.socket}
file_server
'';
};
# Override an environment variable
env.APP_URL = "http://shopware.swag";
}
Refer to the official devenv documentation to get a complete list of all available services and their configuration possibilities:
<PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:
{
services.blackfire.enable = true;
services.blackfire.server-id = "<SERVER_ID>";
services.blackfire.server-token = "<SERVER_TOKEN>";
services.blackfire.client-id = "<CLIENT_ID>";
services.blackfire.client-token = "<CLIENT_TOKEN>";
}
<PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:
{
languages.php.package = pkgs.php.buildEnv {
extensions = { all, enabled }: with all; enabled ++ [ amqp redis blackfire grpc xdebug ];
extraConfig = ''
# Copy the config from devenv.nix and append the XDebug config
# [...]
xdebug.mode=debug
xdebug.discover_client_host=1
xdebug.client_host=127.0.0.1
'';
};
}
<PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:
{
services.mysql.package = pkgs.mariadb;
}
If you decided against using direnv, keep in mind that on every change to the
*.nix files you need to manually reload the environment:direnv reload
The bigger your project directory is getting over time (e.g. cache files piling up), the slower direnv will be. This is a known issue and the devenv developers are working on a solution.
Periodically run
devenv gc to remove orphaned services, packages and processes and free up disk space.Be aware that you cannot connect using the
localhost socket. Instead, you must use 127.0.0.1.The database is stored in the
<PROJECT_ROOT>/.devenv/state/mysql directory.The binaries can be found in the
<PROJECT_ROOT>/.devenv/profile/bin directory.This comes in handy if you want to configure interpreters in your IDE.
Last modified 1h ago