# Installation

**If you have not found an answer to your issue** here, but happened to resolve it on your own / with help of the community - please open a pull-request, or an issue with solution details.

Alternatively, write to us in [Slack](https://join.slack.com/t/scandipwa/shared_invite/enQtNzE2Mjg1Nzg3MTg5LTQwM2E2NmQ0NmQ2MzliMjVjYjQ1MTFiYWU5ODAyYTYyMGQzNWM3MDhkYzkyZGMxYTJlZWI1N2ExY2Q1MDMwMTk).

## “Type Error occurred when creating object: ..\Search\Response\QueryResponse”

The wrong version of elastic-search is installed. This might happen after migration to 2.14.0 from versions bellow. Try the following:

```bash
dcf down # stop the stack
docker volume ls | grep elasticsearch-data # lookup your project elastic-search volume
docker volume rm <YOUR_VOLUME_NAME> # remove the old volume
dcf pull # pull latest images, should include latest start.sh which sets M2 to right ES version
dcf up -d # start the stack again
```

## Search does not work, product can not be saved, can not complete checkout, Magento throwing: `Indexer handler is not available`

The `elasticsearch` is might not be working. The reason of problems above can be seen in the logs of application container, to see the logs, use:

```bash
docker-compose logs -f app
```

There you will see the message saying “indexer is not available”. The **elasticsearch** is an indexer of Magento 2 (by our configuration). Make sure this container (the container will be named `scandipwa-base_elasticsearch_1`) is `up`:

```bash
docker-compose ps
```

If `elasticsearch` is showing `stopped` status, then it is down and must be restarted. But there must be a reason of elasticsearch stop. Check the logs of this container:

```bash
docker-compose logs -f elasticsearch
```

If you see an error log related to `max_map_count` value being to low, do following:

On your **host** machine, execute following command:

```bash
sudo sysctl -w vm.max_map_count=262144 # for too low `max_map_count`
```

{% hint style="warning" %}
**Note:**

to set this values permanently, follow [this guide](https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html#vm-max-map-count).
{% endhint %}

After this, you can restart the `elasticsearch` container. To do it:

```bash
docker-compose restart elasticsearch
```

If for some reason issue persits, and the `elasticsearch` container keeps getting stopped after restart - you have a temporary option to switch the indexer itself.

To switch indexer, in Magento 2 admin, go to: *Stores > Configuration > Catalog > Catalog > Catalog Search > Search Engine* and set to `MySQL`.

{% hint style="warning" %}
**Note:**

after the next deploy, this value will be switched back to `elasticsearch` as this setting is set during the deploy.
{% endhint %}

## The site does not open at all / loads forever

Sometimes the nginx can not find `varnish` host. Execute following commands:

```bash
# if you have the alias set up
dc restart nginx ssl-term
dc restart varnish

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml restart nginx ssl-term
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml restart varnish
```

## The `503 backend fetch failed`

Execute following commands:

```
# if you have the alias set up
dc restart varnish

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml restart varnish
```

## The `502 bad gateway` in production-like setup

First, check if the `app` container is `up`. You can do this by executing (look for the `scandipwa-base_app_1` container status):

```bash
docker-compose ps
```

If the `app` container is up, then you need to see the application logs to make a decision.

You can see when the application is ready to receive connections by watching `app` logs, using this command:

```bash
# if you have the alias set up
applogs

# without aliases (not recommended)
docker-compose logs -f --tail=100 app
```

If you can see following output, the application is ready!

```bash
NOTICE: ready to handle connections
```

Wait for output above, afterwards, the `502` error should be resolved.

If the app is ready to handle connections, but the site still respond with `502`, you might want to look into `app` logs a little deeper. Execute:

```bash
docker-compose logs -f app
```

Scroll those logs to the very top and see if any `error` appears. If it does, search for this error mentions in this FAQ. If there are no error, execute the same instructions as in the **The nginx can not find `varnish` host** FAQ section.

## The `composer` related issues

Inspect the `app` container logs, using following command:

```bash
# if you have the alias set up
applogs

# without aliases (not recommended)
docker-compose logs -f --tail=100 app
```

If you find the following error in the logs:

```bash
Please set COMPOSER_AUTH environment variable
```

Make sure you have a valid Magento 2 `COMPOSER_AUTH` set. This is an environment variable set on your host machine. To test if it is set, use:

```
env | grep COMPOSER_AUTH
```

If the output of this command is empty, or, if the output (JSON object) does not contain `"repo.magento.com"` key, you need to set / update the environment variable.

1. Make sure you have a valid Magento account. You can [create](https://account.magento.com/applications/customer/create/) or [login to existing one](https://account.magento.com/applications/customer/login/) on Magento Marketplace site.
2. Upon logging to your Magento Marketplace account follow the [official guide](https://devdocs.magento.com/guides/v2.3/install-gde/prereq/connect-auth.html) to locate and generate credentials.
3. Now, using the following template, set the environment variable:

```bash
export COMPOSER_AUTH='{"http-basic":{"repo.magento.com": {"username": "<PUBLIC KEY FROM MAGENTO MARKETPLACE>", "password": "<PRIVATE KEY FROM MAGENTO MARKETPLACE>"}}}'
```

To set the environment variables follow [this guide](https://www.serverlab.ca/tutorials/linux/administration-linux/how-to-set-environment-variables-in-linux/). Make sure to make them persist (stay between reloads).

If upon ispection you see a different error:

```bash
COMPOSER_AUTH environment variable is malformed, should be a valid JSON object
```

Check if the environment variable is set properly, it must be valid JSON object.

This issue is common with AWS ECS setups. If you happened to use one, make sure to set it in the following way (without quotes):

```bash
{
    "name": "COMPOSER_AUTH",
    "value": "{\"http-basic\":{\"repo.magento.com\": {\"username\": \"<PUBLIC KEY FROM MAGENTO MARKETPLACE>\", \"password\": \"<PRIVATE KEY FROM MAGENTO MARKETPLACE>\"}}}"
}
```

If the different, `Invalid credentials ...` error appears, like this, for example:

```bash
# the general one, like this:
Invalid credentials for 'https://repo.magento.com/packages.json', aborting

# the more specific one, like this:
The 'https://repo.magento.com/archives/magento/framework/magento-framework-102.0.3.0.zip' URL required authentication.
```

This indicates on:

* issue with credentials, try obtaining new ones from Magento Marketplace.
* the `COMPOSER_AUTH` might be valid JSON, but missing the `"repo.magento.com"` key in it. Again, refer to the instruction above to obtain tokens.

## The `orphans` warning

If the following waring appears during infrastracture run (using `up -d`):

```bash
WARNING: Found orphan containers (scandipwa-base_frontend_1) for this project. If you removed or renamed this service in your compose file, you can run this command with the --remove-orphans flag to clean it up.
```

This indicates you missed the `--remove-orphans` flag. Please run your setups using it, like so:

```bash
# if you have the alias set up
dc up -d --remove-orphans

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml up -d --remove-orphans
```

Or in **development** setup:

```bash
# if you have the alias set up
dcf up -d --remove-orphans

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml -f docker-compose.frontend.yml up -d --remove-orphans
```

## The `index.php` in URL

This is common Magento issue. To resolve it, you need to go into Magento 2 admin. From there:

1. Go to *Stores > Configuration > General > Web > Search Engine Optimization > Use Web Server Rewrites* set them to `Yes`
2. Go to *Stores > Configuration > General > Web > Base URLs* check they end with `/`
3. Go to *Stores > Configuration > General > Web > Base URLs* (Secure) check they end with `/`

## The `404` on homepage

If the homepage shows `404` - there could be multiple reasons. Check following configurations:

1. Go to *Stores > Configuration > General > Web > Default Pages > CMS Home Page* and check if it is set
2. Go to *Content > Pages* make sure the column `Store View` is not empty for your Home Page CMS page. If it is empty, click on the page, select necessary stores and click save (the stores might appear selected, igonre it).

## The `Operation not permited` (permission issues)

If at any point when looking on logs of the `app` container the following message pops up:

```bash
<ANY ACTION> Operation not permited
```

You have a permission issue. To resolve it, run following command on your host machine, from the `scandipwa-base` project directory:

```bash
sudo chmod -R 777 .
```

Why this issue occurred?

You could have ran some command in the `app` container as `root` user. You must run them from `user`. How?

```bash
# use `inapp` alias to get inside of the `app` container as `user`
inapp bash

# use `-u user` argument to execute as a user
docker-compose exec -u user app
```

## The `ERR_CERT_REVOKED` in Chrome

If the Google Chrome shows following issue in Chrome:

```bash
NET::ERR_CERT_REVOKED > issuer: ScandiPWA ...
```

Then, there are some problems with generated certificate. As a solution to that porblem, try:

1. Import & trust the `opt/cert/scandipwa-fullchain.pem` from the project source directory
2. Type `thisisunsafe` on the certificate error page

## The `address already in use` error on setup

If following error appears on container startup:

```bash
ERROR: for <CONTAINER NAME> Can not start service ... : listen tcp 0.0.0.0:<PORT>: bind: address already in use
```

This indicates that one or multiple ports required for the setup are already in use by other processes. Please make sure following ports are not in use: `80, 334, 3307, 1080, 5601`.

See [this instruction](https://appuals.com/how-to-kill-process-on-port/) to find out how to kill processes on specific ports.

## Database migration failed

First time, when uploading a demo-dump, you might stumble across the error:

```bash
Database migration failed: manual action required
```

This could mean, that the database dump apply was not executed successfully. In order to resolve this, run the migration again, but manually:

```bash
# if there is no mysql installed locally
docker ps | grep mysql # get the container ID (i.e. d7886598dbe2)
docker cp deploy/latest.sql <CONTAINER ID>:/tmp/dump.sql
docker-compose exec mysql bash
mysql -u root -pscandipwa -e "DROP DATABASE magento; CREATE DATABASE magento;"
mysql -u root -pscandipwa magento < /tmp/dump.sql


# or if you have a mysql locally installed
mysql -h localhost -P 3307 --protocol=tcp -u root -pscandipwa < deploy/latest.sql
```

## The `ENV_VARIABLE` variable is not set

If when setting up, you notice the following issue:

```bash
# note: PROJECT_IMAGE is an example variable
WARNING: The PROJECT_IMAGE is not set. Defaulting to a blank string.
```

Your machine does not support symlinks. Possibly, you are setting up on Windows. To resolve the issue, fix following files: `.env` and `.application`. To fix them, replace the content of those files with the content of the file mentioned inside. So, for example:

```bash
.env # replace content with deploy/local/env
```

## Ratings are not displayed

First time, when uploading a demo-dump, the rating might not be properly displayed.

To resolve this, follow simple steps:

1. Go to *Stores > Attributes > Rating*
2. Click on every in the list and make sure the `visiblity` is set right

## Composer: `requirements could not be resolved`

When installing a theme using `scandipwa/installer` the following (or similar) error might appear:

```bash
Your requirements could not be resolved to an installable set of packages.
```

This could indicate to current Magento version not matching the the latest version of `scandipwa/installer`. To resolve this:

* For Magento versions below 2.3.3 please use installer ^1.0. Use following command

```bash
composer require scandipwa/installer ^1.0
```

{% hint style="warning" %}
**Note:**

This will install older versions of ScandiPWA, and we suggest to upgrade Magento to 2.3.3 to make it possible to use latest ScandiPWA versions.
{% endhint %}

## Content customization does not work

If the customization selected in the BE configuration (*Stores > Configuration > ScandiPWA > Color customization*) is not working (not opening at all):

* Update the customization module to `1.0.1^` using following command:

```bash
composer update scandipwa/customization
```

* Alternatively, make sure, there exists at least one:
  * CMS block
  * visible on frontend Attribute
  * Scandiweb Menu

## Customization is not displayed

If the customization selected is not displayed on FE, check the `frontend` container. It must be `stopped`, or not running at all. The command for this:

```javascript
# if you have the alias set up
dcf ps | grep frontend

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml ps | grep frontend
```

Must output nothing, or `stopped` in the container status. If it is running, the re-create the setup without frontend container:

```javascript
# if you have the alias set up
dc up -d --remove-orphans

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml up -d --remove-orphans
```

{% hint style="warning" %}
**Note:**

the customization does not work in “development” mode - when the `frontend` container is running.
{% endhint %}

## Luma theme is displayed

If after following all steps of installation the `Luma` or other default theme keeps showing make sure following is true:

1. On the server (in the container) the theme folder (`app/design/frontend/<VENDOR>/<NAME>`, in docker-setup `app/design/frontend/Scandiweb/pwa`) has the folder named `Magento_Theme` inside. This folder must not be empty. It should contain two other folders. If this is not true, from themes root folder execute:

```bash
npm ci && npm run build
```

```bash
This should install and compile the theme, after command execution, the folder should appear. If it does not - you might have stumbled upon some compilation issue, please read the compilation logs to found out where and why.
```

2\. The theme is set in admin. To check the *Content > Design > Themes* (from Magento admin) and make sure your store has a ScandiPWA theme set.

3\. In case all of above are true, but the theme is not appearing, please execute following:

```bash
magento c:f
```

```bash
Check the frontend again after that.
```

## Invalid regular expression: missing /

If you see the blank screen and the browser console is showing an error:

```bash
Uncaught SyntaxError: Invalid regular expression: missing /
```

{% hint style="warning" %}
**Note:**

these steps require validation, please report in Slack what fixed that issue for you!
{% endhint %}

Validate tree, simple things:

* You ran `npm ci` not `npm i`
* You have not run `npm update`
* Your NodeJS higher than `10.5.0`, tested on `10.19.0`

After fix of any of those issues, rebuild a theme.

## Missing package.json file

If when setting up for the first time the following error appeared:

```bash
ENOENT: no such file or directory, open '<PATH_TO_THEME_FOLDER>/package.json'
```

You have executed the installation in the wrong order. First must come the **production**-like setup (`dc`), and only then **development** (`dcf`). To resolve:

1. Removed the theme folder, remove the `<THEME_VENDOR_NAME>/<THEME_NAME>` (by default `Scandiweb/pwa`), like this:

```bash
rm -rf <PATH_TO_THEME_FOLDER>
```

2\. Re-run the setup in **production**-like mode:

```bash
# if you have the alias set up
dc up -d --remove-orphans

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml up -d --remove-orphans
```

3\. Wait until the application finishes starting, using the following command:

```bash
# if you have the alias set up
applogs

# without aliases (not recommended)
docker-compose logs -f --tail=100 app
```

4\. Re-run the **development** setup:

```bash
# if you have the alias set up
dcf up -d --remove-orphans

# without aliases (not recommended)
docker-compose -f docker-compose.yml -f docker-compose.local.yml -f docker-compose.ssl.yml -f docker-compose.frontend.yml up -d --remove-orphans
```

{% hint style="info" %}
**Remember:**

initial project setup must happen in **production**-like mode. Only later (on next run) you can switch to **development**.
{% endhint %}

## ERROR: for unauthorized …

In case issue like this is displayed, you need to login into docker-hub. Then docker will allow you to pull necessary images. See [official instruction](https://docs.docker.com/engine/reference/commandline/login/) to login.

## Media not found

Make sure that you follow the manual media installation instructions for your operating system - [MacOS](https://docs.scandipwa.com/start-and-upgrade/mac-docker-setup) or [Linux](https://docs.scandipwa.com/start-and-upgrade/linux-docker-setup).

{% hint style="warning" %}
**Note:**

Important that your media folder is path is `<PATH TO PROJECT ROOT>src/pub/media`. Such path is NOT correct `<PATH TO PROJECT ROOT>src/pub/media/media`.
{% endhint %}

## Docker - port is already allocated

If port is already allocated when running for steps - setup guide steps - Start the development-setup (optional) or Start the infrastructure in production-like mode:

```bash
$ docker-compose -f docker-compose.yml -f docker-compose.local.yml up
```

In order to fix it you have to stop aall running containers:

```bash
$ docker stop $(docker ps -aq)
# OR
$ sudo service <apache2> stop
```

After that and run launch command again:

```bash
$ docker-compose -f docker-compose.yml -f docker-compose.local.yml up
```

## dc and dcf won’t work at the same time

If you have dc and dcf running at the same time during steps - - Start the development-setup (optional) or Start the infrastructure in production-like mode it won’t work. You have to terminate one of them.

## ERROR: cp: missing destination file operand after

Run the following commands:

```bash
$ cd <PATH TO PROJECT ROOT>/opt/cert
$ sudo cp -f scandipwa-ca.pem /usr/local/share/ca-certificates/scandipwa-ca.pem
```

## ERROR: Shell - NET::ERR*CERT*AUTHORITY\_INVALID

Delete old certificate, create a new one and add it to the list of trusted certificates.

## ERROR: please set composer\_auth environment variable

Delete old certificate, create a new one and add it to the list of trusted certificates.

## ERROR: Database migration failed: manual action required

The error can be experienced on the installation step “Start the development-setup (optional)” after running the following command:

```bash
$ docker-compose -f docker-compose.yml -f docker-compose.local.yml up
```

Resolve it by running the following commands:

```bash
$ composer update
$ docker-compose up
```

## How to add scandipwa-ca.pem into keychain for Ubuntu for base installation?

There is no need to add it to keychain. Simply add it to Chrome:

1. Go to chrome://settings/certificates
2. Open ""Authorities""
3. Add new one
4. Make sure it is trusted to identify websites.

## How to install ScandiPWA with docker from scratch with Magento?

Please follow [the docker installation guide](https://docs.scandipwa.com/start-and-upgrade/linux-docker-setup).

## Does ScandiPWA support VMWare setup?

Currently only Linux and Mac local setup guides are provided and maintained. Please reach out in [community Slack](https://scandipwa.com/community#join-slack) for specific questions regarding other OS.

## ERROR: NET::ERR*CERT*REVOKED > Issuer: ScandiPWA Certificate Authority

Import the file scandipwa-fullchain.pem and allow both certifications.

## ERROR: listen tcp 0.0.0.0:80: bind: address already in use

The problem is that the port is already in use. Make sure to stop all other services running on port 80 to free it up.

## How to setup crons to allow the GraphQL queries when front-end is running on a different domain?

Follow [the remote Magento 2 installation guide](https://docs.scandipwa.com/start-and-upgrade/setting-up-the-theme-with-remote-m2-server).

## Error during installation upon first bootstrap

Enter the container inapp bash and run the following command:

```bash
magento se:un
```

After that re-create the stack.

## Directory /var/www/public/app/design/frontend/Scandiweb/pwa folder is completely empty

In order to resolve this run the following command:

```bash
php bin/magento scandipwa:theme:bootstrap Scandiweb/pwa
```

After that:

1. Shut down all the docker instances and start the up without frontend one
2. Wait docker instances come up and then
3. Start the frontend one

## Can I install ScandiPWA on Debian?

Windows is not supporting symlinks. You can simply copy file instead of symlinking.

Make sure that .env and .application are present in your project directory.

## Unable to setup ScandiPWA on the existing Magento 2.3.3 Enterprise edition

The issue is caused by ScandiPWA slider not supporting PHP 7.3

## ERROR: Exception #0 (InvalidArgumentException): Required parameter ‘theme\_dir’ was not passed

This error happens if theme is set up but is not compiled or wrong theme is selected in admin. You can check it in Magento\_Theme folder which is located in ./app/design/frontend/Scandiweb/pwa.

## Will ScandiPWA theme work without Varnish?

Varnish is an essential part of ScandiPWA. For easy and quick setup we recommend [Docker Installation](https://docs.scandipwa.com/start-and-upgrade/linux-docker-setup) as it has needed services including Varnish pre-configured.

## ERROR: Can’t resolve ‘…/pwa/src/app/index.js’ in ‘…/app/design/frontend/Scandiweb/pwa’

Vendor folder is missing. You have to add it.

## After installing ScandiPWA in production mode nothing is displayed in store and 502 is returned from /admin

Restart Nginx, ssl-term and Varnish.

## ERROR: Exception #0 (CredisException): NOAUTH Authentication required

Your Redis doesn’t have password setup but you are trying to connect using a password. Try not setting password at all.