{"id":45806436,"url":"https://github.com/checkmarble/marble-backend","last_synced_at":"2026-02-26T14:01:29.052Z","repository":{"id":218760633,"uuid":"617669627","full_name":"checkmarble/marble-backend","owner":"checkmarble","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-25T22:01:09.000Z","size":8446,"stargazers_count":45,"open_issues_count":16,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-26T00:53:52.843Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/checkmarble.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-03-22T21:33:18.000Z","updated_at":"2026-02-25T22:01:12.000Z","dependencies_parsed_at":"2024-03-11T10:30:19.743Z","dependency_job_id":"ccb0ad0b-de9a-4833-a0e5-b7ab2524488e","html_url":"https://github.com/checkmarble/marble-backend","commit_stats":null,"previous_names":["checkmarble/marble-backend"],"tags_count":155,"template":false,"template_full_name":null,"purl":"pkg:github/checkmarble/marble-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkmarble%2Fmarble-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkmarble%2Fmarble-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkmarble%2Fmarble-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkmarble%2Fmarble-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/checkmarble","download_url":"https://codeload.github.com/checkmarble/marble-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkmarble%2Fmarble-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29861805,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T08:51:08.701Z","status":"ssl_error","status_checked_at":"2026-02-26T08:50:19.607Z","response_time":89,"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":[],"created_at":"2026-02-26T14:01:26.271Z","updated_at":"2026-02-26T14:01:29.046Z","avatar_url":"https://github.com/checkmarble.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nThis repo is the Marble backend implementation:\n\n- 1 single go app\n- Postgres DB\n\n## Getting Started\n\n### Setup your environment\n\n\u003e **Disclaimer**\n\u003e\n\u003e This repository’s README file is intended for internal use by our development team. The documentation provided here is specifically designed for setting up and running the project on macOS.\n\u003e\n\u003e While external contributions and interest are appreciated, please note that we do not officially support setups on other operating systems. If you encounter issues outside of the macOS environment, support may be limited.\n\u003e \n\u003e For general documentation and user-facing guides, please refer to our main repository: [Marble Documentation](https://github.com/checkmarble/marble/blob/main/README.md).\n\n[Install mise-en-place](https://mise.jdx.dev/getting-started.html) or alternatively [install Go](https://go.dev/doc/install) manually on your laptop (see the version in go.mod).\n\nCreate your own `.env` file based on `.env.example`. You can customize it with your own values, but it should work locally with the default values (except for third-party service functionalities).\n\n#### Setup the Database and Services\n\nLaunch the Postgres DB and other services used by the backend:\n\n```sh\ndocker compose up -d\n```\n\n\u003e NB: It creates a `marble-backend_postgres-db` volume to store PG data.\n\n#### Firebase emulator suite for local development\n\nInstall the [Firebase tools](https://firebase.google.com/docs/emulator-suite):\n\n```sh\n# Install the Firebase CLI\ncurl -sL https://firebase.tools | bash\n\n# Check the version is at least 13.16.0\nfirebase --version\n\n# Login to firebase cli\nfirebase login\n```\n\nThen copy the `./contrib/firebase-local-data.example` folder to `./firebase-local-data`. This folder will be used to store the local data of the Firebase emulator. It is ignored by git.\n```\ncp -r ./contrib/firebase-local-data.example ./firebase-local-data\n```\n\nThen start it using (replace `[GOOGLE_CLOUD_PROJECT]` with the value from your `.env` file):\n\n```sh\nfirebase --project [GOOGLE_CLOUD_PROJECT] emulators:start --import=./firebase-local-data --export-on-exit\n```\n\n\u003e NB: The `--import` flag is used to import the local data into the emulator. The `--export-on-exit` flag is used to export the data when the emulator is stopped so you don't lose your changes.\n\n### Launch the project\n\n#### Share library dependencies\n\nMarble depends on the following shared libraries to be compiled and run. It is required for you to install the follow libraries and their development headers for the project to work properly:\n\n * [`libgeos`](https://github.com/libgeos/geos)\n\n#### Build from source\n\n Export your `.env` file (e.g [mise](https://mise.jdx.dev/)) and run the root of the project:\n\nThe backend project is made of five discrete components:\n\n - The API server\n - The background worker\n - The scheduled executor\n - The data ingestion worker\n - The pending webhook handler\n\nDepending on which feature you need while developing, you should run one or more of those services. The last three are one-off commands that are usually run in cron and do not need to run in the background. The worker, though, handles all asynchronous background tasks the API needs (such as index creation) and might be requireed for some of the API functionnality to work properly.\n\nThe `docker compose` of this repository only contains the _dependencies_ required to run the backend service, but does not start the services themselves. It is assumed the developer will run them themselves.\n\n \n```sh\nmise exec -- go run . --migrations --server\nmise exec -- go run . --worker\n```\n\nAlternatively without mise, export your `.env` file (e.g. using [direnv](https://direnv.net/)) :\n```sh\ngo run . --migrations --server # To start the API\ngo run . --worker # To start the worker\n```\n\nIf you need to run the one-off components (for example if you are working on background data ingestion or on scheduled scenario execution), run them directly from your editor or the terminal when required:\n\n```sh\nmise exec -- go run . --scheduled-executer\nmise exec -- go run . --send-pending-webhook-events\nmise exec -- go run . --data-ingestion\n```\n\nAlternatively, without mise :\n```sh\ngo run . --scheduled-executer\ngo run . --send-pending-webhook-events\ngo run . --data-ingestion\n```\n\n\u003e Using VSCode, you can also run the `Migrate and Launch (.env)` task in the \"Run and debug\" tab. This will load your env file, migrate the DB and start the server. Other components can also be started with the appropriately-named tasks.\n\n## Application flags\n\nThe application can be run with the following flags:\n\n- `--migrations`: run the migrations\n- `--server`: run the server\n- `--scheduled-executer`: execute scheduled scenario job\n- `--data-ingestion`: run data ingestion job\n- `--cron-scheduler`: background job that automatically runs the cron jobs\n- `--send-pending-webhook-events`: retry sending failed webhooks\n\n\u003e NB: `.vscode/launch.json` contains the configuration to run the app with these flags.\n\n## API\n\nThe routing of the application is defined inside `api/routes.go`.\n\nFor further information on the API, you can also refer to the following resources:\n\n- [our API docs](https://docs.checkmarble.com/reference/introduction-1) for public facing reference\n- the Open API Specification defined in the frontend repository [here](https://github.com/checkmarble/marble-frontend/blob/main/packages/marble-api/scripts/openapi.yaml).\n\n## DB Seed and migrations\n\nThe application uses [goose](https://github.com/pressly/goose) to manage migrations.\n\nMigrations are located in the `repositories/migrations` folder.\n\nExecute the program with flags `-migrations` to run migrations.\n\nTo create a new migration, you can use the following command from within the `repositories/migrations` folder\n\n```sh\ngoose create add_some_column sql\n```\n\nIt happens that the migrations end up being misordered. This happens if two people pushed new migrations A and B, B having a timestamp greated than A, but B B is commited first to main. The issue can occur when pushing to the main branch, or when pulling changes from remote main to the local branch. In this case, you may need to roll back a few local migrations before you can migrate up again.\n\nThe easiest way of doings this is by installing the goose cli with brew (`brew install goose`), configuring the goose environment variables\n(typically `export GOOSE_DRIVER=postgres GOOSE_DBSTRING=\"user=postgres dbname=marble host=localhost password=marble\" GOOSE_MIGRATION_DIR=\"./repositories/migrations\"` should work),\nand then running `goose down` as many times as needed from the repository root folder. See also [the goose doc](https://github.com/pressly/goose).\n\n##### (VSCode) Install recommended VSCode extensions\n\nThere is a recommended extensions list in the `.vscode/extensions.json` file.\n\nAll required configuration settings are already included inside the `.vscode/settings.json` file.\nRecommended settings are in the `.vscode/.user-settings.sample.json` file. Cherry-pick them to your user config file.\n\n## FAQ\n\n### How to update firebase local data ?\n\n- Run firebase emulator with paramater: `--export-on-exit`\n- Add user, change options...\n- Exit the emulator\n\n\u003e NB: The data will be saved in the `./firebase-local-data` folder. If you want to share the data, you can copy it to `./contrib/firebase-local-data.example` and commit it.\n\n### How to reset the DB ?\n\n`docker volume rm marble-backend-postgres-db` deletes the PG volume, useful to reset the app to a known state\n\nIn practice, this single-line will delete the stack and create a new one:\n`docker compose down \u0026\u0026 docker volume rm marble-backend-postgres-db \u0026\u0026 docker compose up -d`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheckmarble%2Fmarble-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheckmarble%2Fmarble-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheckmarble%2Fmarble-backend/lists"}