# Environment Setup Issues

### The environment isn't starting

If Kerno is failing to start your application and it's dependencies, try the following troubleshooting steps:

* Make sure you project contains a valid Dockerfile at the root directory of your workspace, so Kerno can use it to start your application. If you don't have one, Kerno will create one for you that you will be able to see in `.kerno/Dockerfile`.
* Make sure your [stack is supported](/docs/getting-started/supported-technologies.md) by Kerno.
* Inspect the Docker Compose YAML file generate by Kerno, and if you see any wrong add guidance to the docker compose.md file to provide Kerno extra context [as shown here](/docs/user-manual/manage-your-test-environment.md). 

{% hint style="warning" %}
Do not modify the generated docker compose YAML directly. Any manual edit will be overwritten by Kerno. All **changes must** go in the `.kerno/docker-compose.md` file so Kerno can apply them safely.
{% endhint %}

### Running Docker without root

Docker must be usable without `sudo`. This is required for Kerno's agents that interact with Docker automatically.

Add your user to the [Docker group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user), you will need to launch a new terminal to make it works:

```bash
sudo usermod -aG docker $USER
# Testing
docker run hello-world
```

#### Docker Buildx Missing

If the `docker compose build` fails with a message like:

```
compose build requires buildx 0.17 or later
```

**Cause:** Docker Compose uses buildx to build images from Dockerfiles (like `.kerno/Dockerfile`). This requirement was identified when running the compose file on EC2 instances where buildx wasn't available.

**Solution:**

1. Install Docker buildx or update Docker to a version that includes buildx by default
   * buildx has been included with Docker since July 2019, so most modern installations should have it
   * If you're on an older system or minimal Docker installation, you may need to update
2. After installing or updating Docker, rerun the `docker compose` command

**Note:** This is typically an edge case encountered on older EC2 instances or minimal Docker installations. Most standard Docker installations already include buildx.

{% hint style="info" %}
If you encounter issues or have questions, [message us on Discord](https://discord.gg/k8yA9tZdP9), and we’ll gladly help.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kerno.gitbook.io/docs/troubleshooting/environment-setup-issues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.