Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
137 lines (81 loc) · 6.23 KB

DEVELOPMENT.md

File metadata and controls

137 lines (81 loc) · 6.23 KB

Development

The following are instructions for setting up your local machine for Flipt development.

Tip

Try our new devenv solution to quickly get setup developing Flipt!

Also check out our Contributing guide for more information on how to get changes merged into the project.

Requirements

Before starting, make sure you have the following installed:

Setup

  1. Clone this repo: git clone https://github.com/flipt-io/flipt.
  2. Run mise install to install required tool versions (Go, Node, etc.).
  3. Run mise run bootstrap to install required development tools. See #bootstrap below.
  4. Run mise run test to execute the Go test suite. For more information on tests, see also here
  5. Run mise run build to build the binary with embedded assets.
  6. Run mise tasks to see a full list of possible commands.

Conventional Commits

Flipt uses Conventional Commits for commit messages. This allows us to automatically generate changelogs and releases. To help with this, we use pre-commit to automatically lint commit messages. To install pre-commit, run:

pip install pre-commit or brew install pre-commit (if you're on a Mac)

Then run pre-commit install to install the git hook.

Bootstrap

The bootstrap task will install all of the necessary tools used for development and testing. Run it with mise run bootstrap.

Configuration

A sample configuration for running and developing against Flipt can be found at ./config/local.yml. To run Flipt with this configuration, run:

./bin/flipt server [--config ./config/local.yml]

To prevent providing the config via config flag every time, you have the option of writing configuration at the location:

{{ USER_CONFIG_DIR }}/flipt/config.yml

The flipt binary will check in that location if a --config override is not provided, so you can just invoke the binary:

./bin/flipt server [--config ./config/local.yml]

The USER_CONFIG_DIR is different based on your architecture, and specified here.

Changes

Changing certain types of files such as the proto or ui files require re-building before they will be picked up in new versions of the binary.

Updating .proto Files

After changing any proto files, you'll need to run mise run proto. This will regenerate the necessary files in the rpc directory.

Tests

To run the tests, you can use the mise run test command. This will run the unit tests.

Mocks

We use mockery to generate mocks for the tests. To regenerate mocks, you can use the mise run go:mockery command.

UI

The UI is built using NPM and Vite and is also statically compiled into the Flipt binary using go:embed.

To develop the project with the UI also in development mode (with hot reloading):

  1. Run mise run ui:dev from the root of this repository. This will start a development server on port 5173 and proxy API requests to the Flipt API on port 8080.
  2. In another terminal, run mise run dev from the root of this repository. This will run the backend server making it accessible on port 8080.
  3. Visit http://localhost:8080 to see the UI.
  4. Any changes made in the ui directory will be picked up by the development server and the UI will be reloaded.

Ports

In development, the two ports that Flipt uses are:

  • 8080: The port for the Flipt REST API
  • 9000: The port for the Flipt GRPC Server

These ports will be forwarded to your local machine automatically if you are developing Flipt in a VSCode Remote Container or GitHub Codespace.

Dev Container

This repository includes a .devcontainer setup for VS Code Remote Containers and GitHub Codespaces.

It provides:

  • A Linux development container with build tools required for Flipt
  • mise for managing Go, Node, and other project tool versions
  • Port forwarding for backend (8080, 9000) and UI dev server (5173)

To use it in VS Code:

  1. Open this repository in VS Code.
  2. Run Dev Containers: Reopen in Container.
  3. Wait for the post-create setup to finish (mise install, mise run bootstrap, and mise run ui:deps).
  4. Start backend and UI in separate terminals:
    • mise run dev
    • mise run ui:dev

Then open http://localhost:8080.

Docker Compose

If you want to develop Flipt using Docker Compose, you can use the docker-compose.yml file in the root of this repository.

This will start two Docker containers:

  • server will run the Flipt server, mounting the contents of this repository as a bind mount. This means that the database (SQLite by default) will be persisted between runs. Currently the server does not support hot reloading, so you'll need to restart the container to pick up any changes.
  • ui will run the UI development server, mounting the ui directory as a bind mount. This means that any changes made to the UI will be picked up by the development server and the UI will be reloaded (thanks to Vite).

To start the containers, run docker-compose up from the root of this repository. After the containers are started, you can visit http://localhost:8080 to see the UI.

devenv

devenv is a solution that creates fast, declarative, reproducible, and composable developer environments using Nix.

To use it for developing Flipt, you'll first need to install it. See the devenv getting started guide for more information.

Once you have devenv installed, you can run devenv up from the root of this repository to start a development environment.

This will start a development environment with the Flipt server running on port 8080 and the UI development server running on port 5173.

devenv