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 ofmix 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 theMIX_ENV
totest
.
You can generate the HTML and EPUB documentation locally using:
mix docs
and opening doc/index.html
in your browser.