# Local Setup

## Clone the repo

{% embed url="<https://github.com/ellie-app/ellie>" %}
Ellie is open source and hosted on GitHub
{% endembed %}

Clone the repo to a local directory with Git

```
$ git clone git@github.com:ellie-app/ellie.git
```

## Get runtime dependencies

Ellie depends on the following projects for local development:

* Required
  * **Docker •** [Homepage](https://docs.docker.com) • [Install](https://docs.docker.com/install/) • for a fully encapsulated runtime environment
* Optional
  * **Kitematic** • [Homepage](https://kitematic.com/) • [Install](https://docs.docker.com/toolbox/) • to inspect and interact with Ellie's containers
  * **PostgreSQL GUIs** • [Wiki](https://wiki.postgresql.org/wiki/Community_Guide_to_PostgreSQL_GUI_Tools) • for dealing directly with Ellie's PostgreSQL database

That's it! All of Ellie's runtime dependencies are managed by Docker, so you don't have to install any of the runtime systems it uses.

{% hint style="warning" %}
Ellie uses your filesystem directly while running locally. If you use any editor tools that manipulate build artifacts from the various platforms Ellie uses then you may end up in an unpredictable state. Ellie's containers run GNU/Linux operating systems, so compiled object files and binaries will target GNU/Linux.
{% endhint %}

## Set required configuration

When you run Ellie locally you will need a couple of environment variables. We try to keep this to a minimum so that set up is as simple as possible. Create a file named `.env.local` into the project root and copy the following variables into it.

{% code title=".env.local" %}

```
SENTRY_DSN=
SENTRY_API_KEY=
```

{% endcode %}

It's okay to leave blank items blank. Their presence is temporarily required for startup but they are only used in production.

## Start the application

Once you have Docker installed, you can use docker-compose to start the application.

```
docker-compose up
```

This command will build and start Ellie's containers. Observe the output until the Webpack server is finished compiling and the Phoenix server is listening on port 4000. The Webpack output will look something like

```
webpack: Compiled with warnings.
Hash: e98b952d5589aa94dbc1
Version: webpack 3.3.0
Time: 48192ms
             Asset     Size  Chunks                    Chunk Names
              0.js  1.24 MB       0  [emitted]  [big]  codemirror-base
              1.js  1.55 MB       1  [emitted]  [big]  codemirror-vim
              2.js   159 kB       2  [emitted]         icons-svg
              3.js  18.4 kB       3  [emitted]         custom-elements-native-shim
              4.js  42.2 kB       4  [emitted]         custom-elements-polyfill
              5.js  1.35 MB       5  [emitted]  [big]
         editor.js  4.97 MB       6  [emitted]  [big]  editor
          embed.js  3.83 MB       7  [emitted]  [big]  embed
      editor-sw.js   940 kB       8  [emitted]  [big]  editor
```

and the Phoenix server will print

```
[info] Running EllieWeb.Endpoint with Cowboy using http://0.0.0.0:4000
```

Both of these servers are configured to recompile and restart when you change source code. The particulars of how that occurs and when containers need to be restarted will require some knowledge of the Phoenix and Webpack development environments.

{% hint style="warning" %}
If for any reason the application does not successfully start after a new build in a newly cloned project, there is something wrong! You can report this as a bug at <https://github.com/ellie-app/ellie/issues>.
{% endhint %}

If you are able to open <http://localhost:4000> and see Ellie running, congrats on successfully starting the project! In the next section we'll learn about how the Ellie server is architected.


---

# 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://docs.ellie-app.com/development/untitled.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.