Local Setup

How to clone and run Ellie on your computer

Clone the repo

GitHub - ellie-app/ellie: The Elm Live EditorGitHub

Ellie is open source and hosted on GitHub

Clone the repo to a local directory with Git

$ git clone [email protected]:ellie-app/ellie.git

Get runtime dependencies

Ellie depends on the following projects for local development:

• Required

  • Docker • Homepage • Install • for a fully encapsulated runtime environment

• Optional

  • Kitematic • Homepage • Install • to inspect and interact with Ellie's containers

  • PostgreSQL GUIs • Wiki • 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.

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.

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.

.env.local

SENTRY_DSN=
SENTRY_API_KEY=

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.

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.

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.