Project: Flipt (Observability and Analysis / Feature Flagging)
File: DEVELOPMENT.md

The following are instructions for setting up your local machine for Flipt development. For info on using VSCode Remote Containers / GitHub Codespaces, see below. [!TIP] Try our new solution to quickly get setup developing Flipt! Also check out our guide for more information on how to get changes merged into the project. Before starting, make sure you have the following installed: (for running tests) Flipt uses to compile SQLite. If you run into errors such as: ```console undefined: sqlite3.Error ``` Then you need to enable CGO. Make sure you have the installed and in your PATH. `set CGO_ENABLED=1` Make sure you have the installed and in your PATH. `export CGO_ENABLED=1` Clone this repo: `git clone https://github.com/flipt-io/flipt`. Run `mage bootstrap` to install required development tools. See below. Run `mage go:test` to execute the Go test suite. Run `mage` to build the binary with embedded assets. Run `mage -l` to see a full list of possible commands. Flipt uses for commit messages. This allows us to automatically generate changelogs and releases. To help with this, we use 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. Flipt is built with Go 1.20+. The `bootstrap` task will install all of the necessary tools used for development and testing. It does this using a seperate tools modules as described here: 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 [--config ./config/local.yml`] To prevent providing the config via config flag every time, you have the option of writing configuration at the location: ```shell {{ USERCONFIGDIR }}/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` The `USERCONFIGDIR` is different based on your architecture, and specified . 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. After changing `flipt.proto`, you'll need to run `mage proto`. This will regenerate the necessary files in the `rpc` directory. The UI is built using and and is also statically compiled into the Flipt binary using . To develop the project with the UI also in development mode (with hot reloading): Run `mage ui:dev` from the root of this

This will start a development server on port `5173` and proxy API requests to the Flipt API on port `8080`. In another terminal, run `mage dev` (or `mage go:run`) from the root of this repository. This will run the backend server making it accessible on port `8080`. Visit `http://localhost:8080` to see the UI. Any changes made in the `ui` directory will be picked up by the development server and the UI will be reloaded. 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. 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. Flipt also supports Containerized Development Environments (CDE) //. These technologies allow you to quickly get setup with a Flipt development environment either locally or 'in the cloud'. For VSCode Remote Containers (devcontainers), make sure you have and the extension installed. Then simply clone this repo, open it in VSCode and run the command in VSCode. Simply open Flipt in a codespaces from the `Code` tab in the repo on GitHub or click the button below: ](https://github.com/codespaces/new/?repo=flipt-io/flipt) To use , simply open Flipt in Gitpod by clicking the button below: ](https://gitpod.io/#https://github.com/flipt-io/flipt) 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 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 Docker container with the Flipt server running on port `8080` and the UI development server running on port `5173`.