{"id":44332366,"url":"https://github.com/bringauto/fleet-protocol-http-api","last_synced_at":"2026-02-11T10:09:53.542Z","repository":{"id":228088440,"uuid":"731223393","full_name":"bringauto/fleet-protocol-http-api","owner":"bringauto","description":"Fleet Protocol External Server HTTP API Implementation","archived":false,"fork":false,"pushed_at":"2025-11-18T13:25:56.000Z","size":838,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-11-18T15:59:37.724Z","etag":null,"topics":["fleet-protocol"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bringauto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-13T15:51:00.000Z","updated_at":"2025-11-18T07:29:40.000Z","dependencies_parsed_at":"2024-03-17T03:48:23.790Z","dependency_job_id":"98ae4464-c37a-4264-9509-a1e65ea73b50","html_url":"https://github.com/bringauto/fleet-protocol-http-api","commit_stats":null,"previous_names":["bringauto/fleet-protocol-http-api"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/bringauto/fleet-protocol-http-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Ffleet-protocol-http-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Ffleet-protocol-http-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Ffleet-protocol-http-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Ffleet-protocol-http-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bringauto","download_url":"https://codeload.github.com/bringauto/fleet-protocol-http-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bringauto%2Ffleet-protocol-http-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29331743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T06:13:03.264Z","status":"ssl_error","status_checked_at":"2026-02-11T06:12:55.843Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fleet-protocol"],"created_at":"2026-02-11T10:09:52.914Z","updated_at":"2026-02-11T10:09:53.532Z","avatar_url":"https://github.com/bringauto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fleet v2 server\n\nThe HTTP API is described by the `openapi.yaml` according to [OpenAPI Specification](https://openapis.org). The base of the server (e.g., entity models) was generated by the [OpenAPI Generator](https://openapi-generator.tech) project. This includes ALL the contents of the `server/fleetv2_http_api` directory EXCEPT for:\n\n- `impl`,\n- `controllers/security_controller.py` (originally created by the Generator).\n\nThese files are included in the `server/.openapi-generator-ignore`. This file also must include itself.\n\n## Doc\n\nFormal specification can be found as part of [HTTP API] document.\n\n## Requirements\n\nPython 3.10.12+\n\n## Usage\n\n### Configuration\n\nThe configuration file is located in `config` directory. The file contains the fields listed below.\n\n**Check carefully the correct name of the database the server should connect to.**\n\n- `logging` - contains the keys `console`and `file` for printing the logs into a console and a file, respectively. The `file` contains field `path` to set the (absolute or relative) path to the directory to store the logs. Both contain the following keys:\n  - `level` - logging level as a string (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Case-insensitive.\n  - `use` - set to `True` to allow to print the logs, otherwise set to `False`.\n- `database` - settings for the database associated with the server.\n  - `server` - settings for the database server. If only `path` is provided under `server`, the database used will be an sqlite file specified by the path.\n    - `username`\n    - `password`\n    - `location` - location of the database (e.g., `localhost`).\n    - `port` - port number.\n    - `database-name` - database name.\n    - `path` - only use this parameter if an sqlite db is needed (no other fields can be used in `server` in that case, otherwise connection to postgresql will we attempted). The value should be a path to a database file (e.g., `/home/user/test.db`). The file will be created if it doesn't exist.\n  - `cleanup` - contains the following keys:\n    - `timing_in_seconds`\n      - `retention_period`- number of seconds after which each message can be deleted after it has been posted to the server.\n      - `cleanup_period` - number of seconds after which the cleanup process will be executed.\n- `http_server`- contains the following keys:\n  `base_uri`- base URI of the HTTP server (e.g., `http://localhost:8080`).\n- `request_for_messages`\n  - `timeout_in_seconds` - number of seconds after which the server will stop waiting for messages from the client and returns empty response.\n- `security` field is further described in the section [Configuring oAuth2](#configuring-oauth2).\n\n### Dependencies\n\nInstall python dependencies into an activated virtual environment:\n\n```bash\npython3 -m venv .venv \u0026\u0026 \\\nsource .venv/bin/activate \u0026\u0026 \\\npip3 install -r requirements.txt\n```\n\n### Running the server\n\nTo run the server execute the following:\n\n```bash\npython3 -m server \u003cpath-to-config-file\u003e [OPTIONS]\n```\n\nThe server automatically connects to the PostgreSQL database using data from the config file. If you want to override these values, start the server with some of the following options:\n\n| Option            | Short  | Description                                  |\n| ----------------- | ------ | -------------------------------------------- |\n| `--username`      | `-usr` | Username for the PostgreSQL database         |\n| `--password`      | `-pwd` | Password for the PostgreSQL database         |\n| `--location`      | `-l`   | Location of the database (e.g., `localhost`) |\n| `--port`          | `-p`   | Port number (e.g., `5430`)                   |\n| `--database-name` | `-db`  | Database name                                |\n\nNote that these data should comply with the requirements specified in SQLAlchemy [documentation](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls).\n\nTo visualize the API, open your browser here (the location and port may vary according to the script parameters or the values in `config/config.json`):\n\n```\nhttp://localhost:8080/v2/protocol/ui\n```\n\nYour OpenAPI definition lives here:\n\n```\nhttp://localhost:8080/v2/protocol/openapi.json\n```\n\n### Adding a new admin to the database\n\nTo generate a new api_key (passed as a query parameter \"api_key\") run the following:\n\n```bash\npython scripts/new_admin.py \u003cnew-admin-name\u003e \u003cpath-to-config-file\u003e [OPTIONS]\n```\n\nThe script automatically connects to the PostgreSQL database using the config file. To override any of those values, run the script with some of the following options:\n\n| Option            | Short  | Description                                  |\n| ----------------- | ------ | -------------------------------------------- |\n| `--username`      | `-usr` | Username for the PostgreSQL database         |\n| `--password`      | `-pwd` | Password for the PostgreSQL database         |\n| `--location`      | `-l`   | Location of the database (e.g., `localhost`) |\n| `--port`          | `-p`   | Port number (e.g., `5430`)                   |\n| `--database-name` | `-db`  | Database name                                |\n\nNote that these data should comply with the requirements specified in SQLAlchemy [documentation](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls).\n\nWorking example for test database built from docker-compose (username and password can be found in the `config/config.json`).\n\n```bash\npython scripts/new_admin.py 'Bob' config/config.json\n```\n\nAfter running the script, the api_key is printed to the console:\n\n```bash\nNew key for admin 'Bob':\n\n\u003cgenerated-api-key\u003e\n```\n\n### Running with Docker\n\nTo run the server on a Docker container, run:\n\n```bash\ndocker compose up --build -d\n```\n\n### Configuring oAuth2\n\nTo get Keycloak authentication working, all parameters in the security section of `config/config.json` need to be filled in. Most information is found in the Keycloak GUI.\n\n```json\n\"security\": {\n        \"keycloak_url\": \"https://keycloak.bringauto.com\",\n        \"client_id\": \"\",\n        \"client_secret_key\": \"\",\n        \"scope\": \"\",\n        \"realm\": \"\"\n    }\n```\n\n- keycloak_url: base URL of a working Keycloak instance\n- client_id: id of client in Keycloak (Clients -\u003e click on client representing HTTP API -\u003e Settings -\u003e Client ID)\n- client_secret_key: secret key of client (Clients -\u003e click on client representing HTTP API -\u003e Credentials -\u003e Client Secret)\n- scope: checking of scopes is not yet implemented (must be `email` for now!)\n- realm: realm in which the client belongs (seen on top of the left side panel in Keycloak GUI)\n\n### Configuration\n\nThe server settings can be found in the `config/config.json`, including the database logging information and parameters for the database cleanup.\n\n## Testing\n\nTesting of a cloned repository requires two steps:\n\n- install this package,\n- run the tests (or their subset).\n\n**Before installation, make sure you have the [virtual environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments) activated.** This is a necessary step to avoid conflicts with the system packages.\n\n### Unit tests\n\nIn the root directory, run the following\n\n```bash\npython -m tests [-h] [PATH1] [PATH2] ...\n```\n\nEach PATH is specified relative to the `tests` directory. If no PATH is specified, all the tests will run. Otherwise\n\n- when PATH is a directory, the script will run all tests in this directory (and subdirectories),\n- when PATH is a Python file, the script will run all tests in the file.\n\nThe `-h` flag makes the script display tests' coverage in an HTML format, for example in your web browser.\n\nThe same applies to integration tests using containerized HTTP servers.\n\n### Integration tests\n\nTo run the integration tests, run the following in the root directory:\n\n```bash\npython -m tests_integration [-h] [PATH1] [PATH2] ...\n```\n\n## Server re-generation\n\nYou must have the OpenAPI Generator installed (see [link](https://openapi-generator.tech/docs/installation/)). Before the server generation, the server must not be running.\n\nTo regenerate the server, run (in the `server` directory):\n\n```bash\nopenapi-generator-cli generate -g python-flask -i ../openapi.yaml -o . -p=packageName=fleetv2_http_api\n```\n\nBelow is an example of running the Generator with the port number being specified (the default is `8080`):\n\n```bash\nopenapi-generator-cli generate -g python-flask -i ../openapi.yaml -o . -p=packageName=fleetv2_http_api,serverPort=\u003cport-number\u003e\n```\n\nIf you have trouble with running the generator, visit [docs](https://openapi-generator.tech/docs/installation/).\n\n\n[HTTP API]: https://ref.bringautofleet.com/r/protocol/http-api/1.0.0/http-api\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbringauto%2Ffleet-protocol-http-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbringauto%2Ffleet-protocol-http-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbringauto%2Ffleet-protocol-http-api/lists"}