Lightning extends the existing OpenFn Digital Public Good, providing a web UI to visually manage complex workflow automation projects.

The easiest way to set up Lightning is via Docker. We have included the necessary files to get everything setup using Docker Compose.

If you'd like to contribute or set things up locally for development, checkout the Contributing section.

• Install Docker
• Check out the repo using git
• Copy the .env.example file to .env
• Run docker compose run --rm web mix ecto.migrate
  This will build the container, and set the database up with the up to date schema.

Once you've done that, you can run docker compose up every time you want to start up the server.

By default the application will be available from localhost:4000.

Troubleshooting

If you're actively working with docker, start experiencing issues and would like to start from scratch you can clean up everything and start over like this:

# To remove any ignored files and reset your .env to it's example
git clean -fdx && cp .env.example .env
# You can skip the line below if you want to keep your database
docker compose down --rmi all --volumes

docker compose build --no-cache web && \
  docker compose create --force-recreate

docker compose run --rm web mix ecto.migrate
docker compose up

We appreciate any contribution to Lightning.

Database

Ensure you have a PostgreSQL database setup and running, here is an example to get it running quickly using docker.

docker volume create lightning-postgres-data

docker create \
  --name lightning-postgres \
  --mount source=lightning-postgres-data,target=/var/lib/postgresql/data \
  --publish 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  postgres:14.1-alpine

docker start lightning-postgres

Elixir & Ecto

We use asdf to help with our local environments. Included in the repo is a .tool-versions file that is read by asdf in order to dynamically make the specified versions of Elixir and Erlang available.

asdf install  # Install language versions
mix local.hex
mix deps.get
mix local.rebar --force
mix ecto.create # Create a development database in Postgres
mix ecto.migrate
mix openfn.install.runtime

Lightning is a web app. To run it, start the development server by running mix phx.server. Once the server has started, head to localhost:4000 in your browser.

Before the first time running the tests, you need a test database setup.

MIX_ENV=test mix ecto.create

And then after that run the tests using:

MIX_ENV=test mix test

We also have test.watch installed which can be used to rerun the tests on file changes.

We use a host of common Elixir static analysis tools to help us avoid common pitfalls and make sure we keep everything clean and consistent.

In addition to our test suite, you can run the following commands:

• mix format --check-formatted
  Code formatting checker, run again without the --check-formatted flag to have your code automatically changed.
• mix dialyzer
  Static analysis for type mismatches and other common warnings. See dialyxir.
• mix credo
  Static analysis for consistency, and coding standards. See Credo.
• mix sobelow
  Check for commonly known security exploits. See Sobelow.
• MIX_ENV=test mix coveralls
  Test coverage reporter. This command also runs the test suite, and can be used in place of mix test when checking everything before pushing your code. See excoveralls.

For convenience there is a verify mix task that runs all of the above and defaults the MIX_ENV to test.

You can generate the HTML and EPUB documentation locally using:

mix docs and opening doc/index.html in your browser.