Contributing¶
General Contribution¶
For general rule regarding contribution to BiznetGio projects. See BiznetGio Contributing Guide
Running the project locally¶
Below is the description of each step needed to run the project locally.
To try the command directly in order, see our playbook examples in docs/examples
.
Cockroachdb¶
It’s recommended to use the CockroachDB docker image instead of installing it locally.
roach:
hostname: roach
image: cockroachdb/cockroach:v19.2.2
command: start --insecure --listen-addr=roach:26257 --advertise-addr=roach:26257 --http-addr=roach:8090
ports:
- "26257:26257"
- "8090:8090"
volumes:
- ./data/cockroach-data:/cockroach/cockroach-data:z
$ # run the cockroach container above
$ docker-compose up -d
$ # create database. `10.0.0.1` is your host IP.
docker run --rm cockroachdb/cockroach:v19.2.2 sql --host=10.0.0.1:26257 --insecure --execute "CREATE DATABASE IF NOT EXISTS knotdb;"
$ # create table. get the `schema.sql` in `api/`
$ cat schema.sql | docker run -i --rm cockroachdb/cockroach:v19.2.2 sql --host=10.0.0.1:26257 --insecure --database=knotdb
This step will give you a running cockroach database, with knotdb
as a name and a schema defined in schema.sql
.
RESTKnot API¶
Clone the project https://github.com/BiznetGIO/RESTKnot/
Go to the API directory
$ cd api/
$ # Install psycopg2 prerequisites
$ sudo dnf install -y libpq-devel # Centos/Fedora/Cygwin/Babun
$ sudo apt install -y libpq-dev # Debian/Ubuntu
$ # Install confluent-kafka prerequisites
$ sudo dnf install -y librdkafka-devel python3-devel # Centos/Fedora/Cygwin/Babun
$ sudo apt install -y librdkafka-dev python3-dev # Debian/Ubuntu
$ # Create the virtualenv, then install the dependencies
$ poetry shell && poetry install
After making changes, you can the restknot-api
using plain flask run
.
Or running it via docker.
If you prefer to run without docker, you need to export the environment variables manually.
See api/docker-compose.example.yml
to learn all available variables.
Using docker, it would be:
$ # build the image
$ docker build -f Dockerfile -t restknot-api:0.7.8 --build-arg BUILD_VERSION=$(git log -1 --format=%h) .
$ # run the image
$ docker-compose up -d
Ensure the app is running by checking the /api/health
endpoint.
Broker¶
For RESTKnot API to communicate with RESTKnot Agent, they need a broker. We use Kafka for the broker.
See docs/example
to run Zookeeper and Kafka. The examples contain
configuration to run multiple Kafka with single Zookeeper or multiple Kafka with
multiple Zookeeper.
RESTKnot Agent¶
To build the agent:
$ cd agent/
$ # build the image
$ docker build -f Dockerfile -t restknot-agent:0.7.8 --build-arg BUILD_VERSION=$(git log -1 --format=%h) .
$ # run the image
$ docker-compose up -d
Set appropriate configurations. Take a look at agent/docker-compose.example.yml
.
Basic Workflow¶
To test that all component works together, or to get an insight into how knot works. See Basic Workflow
Releasing¶
To create a release. Run the following steps.
- Run linting
just check
. To check if the codebase adheres to the rules. - Update the CHANGELOG.
- Update version numbers using
./scripts/bump_version <old-version> <new-version>
. - Create a commit with a message format: v[0-9]+.[0-9]+.[0-9]+, and push it to a feature branch (as a pull request).
- Wait for a check to pass, merge the specified pull request to the master branch.
- Wait for a check to pass, create a release tag from GitHub UI, then copy the appropriate CHANGELOG to the release page.