Skip to content

Update commands to work with 6.4 and add package.json for docs:preview #1175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 8, 2023
Merged

Update commands to work with 6.4 and add package.json for docs:preview #1175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
217 changes: 185 additions & 32 deletions guides/installation/devenv.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,26 @@ docker run -it nixos/nix
</Tab>
</Tabs>

#### Using Oh My ZSH?

You probably won't be able to use the commands below. Use the following steps to continue using [oh my zsh](https://ohmyz.sh/):

* Open `/etc/zshrc` and look for the following lines (probably at the end of the file):

```bash
# Nix
if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
. '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
fi
# End Nix
```

* Copy these lines and delete them from this file.
* Open `~/.zshrc` and add the above-copied lines to the end of this file.
* Initiate the terminal with `source ~/.zshrc` or reboot your terminal for nix to work.

[Credits: "nixos installation issue,'command not found: nix'", StackOverflow](https://stackoverflow.com/a/70822086/982278)

### Cachix

Next, install [Cachix](https://www.cachix.org/) to speed up the installation:
Expand All @@ -73,7 +93,7 @@ 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.
> This user doesn't have permission to configure binary caches.
>
> You can either:
>
Expand Down Expand Up @@ -101,37 +121,38 @@ Before booting up your development environment, configure Cachix to use Shopware
cachix use shopware
```

By default, `shopware/platform` uses unfree software like Blackfire. To be able to use unfree software, you have to *allow* it:

```bash
mkdir -p ~/.config/nixpkgs
echo '{ allowUnfree = true; }' > ~/.config/nixpkgs/config.nix
```

You can find the whole installation guide for devenv in their official documentation:

<PageRef page="https://devenv.sh/getting-started/" title="Getting started - devenv.sh" target="_blank" />

### Shopware

Depending on whether you want to set up a fresh Shopware project or contribute to the Shopware core, choose between:
Depending on whether you want to set up a fresh Shopware project or contribute to the Shopware core, you have to choose between the [Symfony Flex template](template) or the Shopware project.

:::info
Since you are using Shopware 6.4 remember to use the dev-flex version `composer create-project shopware/production:dev-flex <project-name>`
:::

<Tabs>
<Tab title="Symfony Flex">
If you are already using Symfony Flex, you require a Composer package to get a basic devenv configuration:
If you are already using our Symfony Flex template, you require a Composer package to get a basic devenv configuration:

```bash
composer require devenv
```shell
cd <YOUR_SHOPWARE_FLEX_PROJECT_ROOT>
```

```shell
composer require "devenv:*"
```

This will create a basic `devenv.nix` file to enable devenv support for Shopware.
</Tab>

<Tab title="shopware/platform (Contribute)">
Clone [shopware/platform](https://github.com/shopware/platform) and change into the project directory:
<Tab title="shopware/shopware (Contribute)">
Clone [shopware/shopware](https://github.com/shopware/shopware) and change into the project directory:

```shell
git clone git@github.com:shopware/platform.git
git clone git@github.com:shopware/shopware.git
```

</Tab>
Expand All @@ -147,6 +168,26 @@ devenv up
Make sure that the ports for the services are not already in use, or else the command will fail.
:::

Check your default web services with the following commands:

<Tabs>
<Tab title="macOS">

```bash
netstat -p tcp -van | grep '^Proto\|LISTEN'
```

</Tab>

<Tab title="Ubuntu">

```bash
ss -tulpn | grep ':80\|:3306\|:6379'
```

</Tab>
</Tabs>

Ensure to change your `.env` file to have the database connect using localhost's IP address instead of the default MySQL socket:

```txt
Expand All @@ -155,7 +196,7 @@ DATABASE_URL="mysql://shopware:shopware@127.0.0.1:3306/shopware?sslmode=disable&
```

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:
This shell includes all needed programs (php, composer, npm, node, etc.) to initialize Shopware:

```shell
devenv shell
Expand All @@ -164,15 +205,15 @@ devenv shell
In the devenv shell, run the following command to initialize Shopware:

```shell
composer setup
bin/console system:install --basic-setup --create-database --force
```

### Direnv

If you wish to switch between multiple development environments which use devenv seamlessly, we recommend installing [direnv](https://direnv.net/).

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.
This means 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:

Expand All @@ -199,7 +240,7 @@ The installation instructions for other OS are available on direnv's [official d
</Tab>
</Tabs>

Afterwards, add the following hook to your shell:
Afterward, add the following hook to your shell:

<Tabs>

Expand Down Expand Up @@ -248,13 +289,27 @@ direnv allow

Here is an overview of services Shopware provides by default and how you can access them:

| Service | Access |
|------------------|------------------------------------------------|
| MySQL | `mysql://shopware:shopware@127.0.0.1:3306` |
| Caddy | [http://localhost:8000](http://localhost:8000) |
| Adminer | [http://localhost:9080](http://localhost:9080) |
| Mailhog (SMTP) | `smtp://127.0.0.1:1025` |
| Mailhog (Web UI) | [http://localhost:8025](http://localhost:8025) |
| Service | Access |
|----------------|-------------------------------------------------|
| MySQL | `mysql://shopware:shopware@127.0.0.1:3306` |
| Mailhog (SMTP) | `smtp://127.0.0.1:1025` |
| Redis (TCP) | `tcp://127.0.0.1:6379` |

### Caddy
Caddy is a powerful, enterprise-ready, open-source web server with automatic HTTPS written in Go.

[http://127.0.0.1:8000](http://127.0.0.1:8000)

### Adminer
Adminer is a full-featured database management tool written in PHP.

[http://localhost:8010](http://localhost:8010)

### Mailhog
MailHog is an email testing tool for developers.

[http://localhost:8025](http://localhost:8025)


## Customize your setup

Expand Down Expand Up @@ -288,7 +343,7 @@ After changing `devenv.local.nix`, please [reload your environment](#manually-re
};

# Override an environment variable
env.APP_URL = "http://shopware.swag";
env.APP_URL = "http://shopware.swag:YOUR_CADDY_PORT";
}
```

Expand Down Expand Up @@ -339,28 +394,118 @@ Refer to the official devenv documentation to get a complete list of all availab
}
```

### Use customized MySQL port

```nix
// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
services.mysql.settings = {
mysqld = {
port = 33881;
};
};

}
```

### Use customized VirtualHosts port for Caddy

<Tabs>
<Tab title="Port">

```nix
// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
services.caddy.virtualHosts = lib.mkForce {
":8029" = lib.mkDefault {
extraConfig = lib.mkDefault ''
@default {
not path /theme/* /media/* /thumbnail/* /bundles/* /css/* /fonts/* /js/* /sitemap/*
}

root * public
php_fastcgi @default unix/${config.languages.php.fpm.pools.web.socket} {
trusted_proxies private_ranges
}
file_server
'';
};
};

}
```

</Tab>

<Tab title="Port and virtual host">

```nix
// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
services.caddy.virtualHosts."http://shopware.swag:8029" = {
extraConfig = ''
root * public
php_fastcgi unix/${config.languages.php.fpm.pools.web.socket}
file_server
'';
};
```

</Tab>
</Tabs>


### Use customized Adminer port

```nix
// <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
services.adminer.listen = "127.0.0.1:9084";
}
```

## Known issues

### Manually reloading devenv

If you decided against using direnv, keep in mind that on every change to the `*.nix` files you need to manually reload the environment:
If you decided against using direnv, keep in mind that on every change to the `*.nix` files you need to manually reload the environment. Run `exit` to quit the current devenv shell and enter the shell again to reload:

```shell
devenv up
devenv shell
```

### Direnv slow in big projects

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.
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.

<PageRef page="https://github.com/cachix/devenv/issues/257" title="Devenv slows down with big code repositories #257" target="_blank" />

### Fail to start Redis with locale other than en_US

```shell
14:04:52 redis.1 | 364812:M 07 Nov 2023 14:04:52.999 # Failed to configure LOCALE for invalid locale name.
```

You can export a different locale to your shell with the following command:

```shell
export LANG=en_US.UTF8;
```

## FAQ

### How do I clean up devenv?

Periodically run `devenv gc` to remove orphaned services, packages and processes and free up disk space.
Periodically run `devenv gc` to remove orphaned services, packages and processes and free-up disk space.

### How do I access the database?

Expand All @@ -381,3 +526,11 @@ The [NixOS package search](https://search.nixos.org/packages) is a good starting
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.

### How do I stop all processes at once?

In case you can't find and stop running devenv processes, you can use the following command to kill them:

```shell
kill $(ps -ax | grep /nix/store | awk '{print $1}')
```
8 changes: 8 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"name": "shopware/docs",
"version": "0.0.1",
"scripts": {
"docs:link": "../developer-portal/docs-cli.cjs link --src . --dst docs --symlink",
"docs:preview": "../developer-portal/docs-cli.cjs preview"
}
}