An open source online comparator that operates ecological scoring, following a common good mindset.
Technical metrics and maven site is deployed on Github Pages:
Open4goods (o4g) is an open-source and open-data product aggregator, search engine and comparator. More over, it is a stack aiming at handling large product datasets identified by GTIN's. It is build upon Maven, Java, SpringBoot, Elasticsearch, Redis, and some other cool libraries. It is mainly designed to :
-
ingest product based data from merchant CSV feeds and URL-oriented review/enrichment sources.
-
aggregate data fragments into well structured product data. The api module orchestrates this through the
AggregationFacadeService, handling scoring, attribute merging, conflict detection and NLP processing. -
Serve data to the Nuxt 3 frontend through the front-api module. The frontend project consumes this API. The legacy ui module is deprecated.
-
Gradually migrate commons and API features into dedicated microservices located under services. This ongoing refactoring aims at a cleaner, service‑oriented architecture.
Open4goods is organised as a multi‑module Maven modulith. Core modules are:
api- central service exposing REST endpoints and aggregation logic.front-api- lightweight API consumed by the Nuxt 3frontend.frontend- Nuxt 3 application working withfront-api.commonsandmodel- shared utilities and domain objects.services/*- independent Spring Boot microservices extracted from the monolith.ui- historical Thymeleaf interface (deprecated).
There are several ways to contribute to the project.
By buying your products on official sites, you "create" money through the affiliation system, that allows to reverse the "by law" 20% environmental compensation. By using it you will also able to provide us some feedbacks
Communication will be the lack of this Odyssey, any kind of help is welcome. Talking about this the project to your granny or even to your dog could help us a lot.
Bugs and ideas are greatly welcome ! We have a specific feedback system that allows you to report feedback to Github Issues directly from your navigation on our frontends.
Verticals (eg : tv's, washing machines, ...) are defined through yaml configuration files. The ecoscore is part of the verticals configurations.
Our verticals definitions are totaly open, meaning that you are very welcome to :
- inspect them, by reviewing the verticals configuration
- comment / question, by posting issues with your concerns
- contribute, by creating new verticals or by updating existing ones with Pull Requests
Contribute to the websites, on the UI, on the content, or on the data aspects. Quiet simple to set-up, you can run open4goods website localy with the below instructions.
Dependencies across Maven modules, Node projects, Docker/Compose images, and GitHub Actions are maintained by Renovate. Ordinary updates are grouped for manual review before 06:00 Europe/Paris time each Monday; major updates require Dependency Dashboard approval, and security fixes remain urgent. See the dependency maintenance and deployment runbook for the complete review and release policy.
Issues are organised using GitHub Projects V2. The workflow
label-to-project.yml automatically
assigns newly opened issues to the right project board based on their labels.
If an issue has no squad:* label or carries the EPIC label, it is routed to
the PMO board and placed in the Triage column. A manual workflow named
label-to-project.yml
can be triggered to reapply these rules to existing issues.
- Fork the repository and create a feature branch.
- Follow Conventional Commits for commit messages.
- Ensure
mvn clean installsucceeds and update documentation. - Open a Pull Request describing why and what.
- Token guidance and the single-writer PR body policy are documented in docs/gh-mcp-workflow.md. Use
GH_TOKENfor gh CLI (PR body edits) andMCP_GITHUB_TOKENfor MCP GitHub comments/labels. - Run
scripts/dev-doctor.shto confirm toolchain (Java 21+, Node 20+, pnpm 10.26.0) and required env vars before pushing.
We will see here how to run open4goods frontends and API's on tour computer.
You will need :
- Java 21+
- Maven
- Elasticsearch and Redis, that can be transparently provided through Docker and Docker Compose
Elasticsearch and Redis are used by the open4goods project. A Kibana instance is commented in the docker-compose.yml file, if you want to browse data's by yourself. Go to the project root, then start the compose file
docker compose up
Docker compose is managed by spring-boot-docker-compose. That means that the manual launching of docker-compose is not mandatory, containers will be started by the application if not present.
Elastic, kibana and Redis should be available on :
- Elastic Search : http://localhost:9200
- Kibana : http://localhost:5601
- Redis : http://localhost:6379
The compose file also defines a frontend-ssr service. During the CI/CD
deployment, the Nuxt build directory (.output) is copied to
/opt/open4goods/bin/latest/frontend-ssr on the server. The container mounts
this path and runs node .output/server/index.mjs to serve the production
frontend.
By default, the front-api runs in Local Mode (local profile, see
front-api/src/main/resources/application-local.yml). This mode starts with no network
access, no token and no pre-existing cache file:
- Simulated: the product repository and the contribution-vote repository are stubbed
in-memory (no real Elasticsearch connection needed to create their beans), as is the brand
referential (empty, instead of GitHub's
brands-company-mapping). - Disabled: the GitHub-backed feedback integration (
feedback.github.enabled: false); creating/listing feedback issues and votes falls back to an in-memory no-op instead of calling the GitHub API. - Degraded, not blocking: the GeoNames (city lookup) and MaxMind (IP geolocation) datasets,
and the Google product taxonomy, still try to download on startup, but a failed download (no
network) leaves them unloaded instead of failing startup -
/actuator/healththen reportsDOWNforgeoNames/maxMind, and verticals simply have no Google taxonomy id attached, which is expected offline, not an error. - Still live and reaching the real internet (not disabled by this profile): the Icecat product/category/feature Elasticsearch repositories use a stub converter just to let their proxies be created without a server; any actual query against them still needs a reachable Elasticsearch, as does the affiliation-partners refresh job and the geocode microservice proxied by the frontend's generated client.
1. Start the Backend (Front-API)
mvn spring-boot:run -pl front-apior, from a built jar:
java -jar front-api/target/front-api-0.0.1-SNAPSHOT.jar --spring.profiles.active=localThe API will start on http://localhost:8082.
Note: Data will be empty and non-persistent.
2. Start the Frontend
cd frontend
pnpm install
pnpm devThe frontend will be available at http://localhost:3000.
To run with a real database and Elasticsearch (e.g., via Docker Compose), use the devsec profile.
- Start Infrastructure:
docker compose up -d
- Start Backend with Profile:
mvn spring-boot:run -pl front-api -Dspring-boot.run.profiles=devsec
The Nuxt frontend reads its API endpoint and cookie names from environment
variables. Create a .env file in frontend/ with:
API_URL=http://localhost:8082
TOKEN_COOKIE_NAME=access_token
REFRESH_COOKIE_NAME=refresh_token
On login, the /auth/login route stores JWT and refresh tokens in HTTP-only
cookies using these names. In production they are marked Secure and
SameSite=None.
Before running the docker compose check that the value of 'vm.max_map_count' is higher or equal to 262144. If not, you will have to raise your max map args to be able to rune the Elastic image, see the Hint's section
Jars are not published to any central repo (nor planned to, it seems not to make any particular sense). To build, please go into the project folder. Then :
mvn install
The open4goods project is packaged under the form of several SpringBoot web applications. You will probably want to launch :
- API component : Play with the data aspect and the business logic
- UI component : Play with the user interface part of the question
From the project root folder, you can now launch the aspects of the platform you are interested in :
UI
java -Dspring.profiles.active=dev -jar ui/target/ui-[VERSION].jar
You should be able to access the open4goods user interface at http://localhost:8082
Api
java -Dspring.profiles.active=dev -jar api/target/api-[VERSION].jar
You should be able to access the open4goods API at http://localhost:8081
If using any kind of IDE (tested with Eclipse and Intellij), please import as maven or SpringBoot project, then run or debug from the following Application classes :
Don't forget to specify the profile to use (probably you'll want "dev" to run in development mode)
For now, you have an up and running open4good platform. You will like to play with some datasets, and like it's not so easy to get them, we provide some live datas directly from our websites.
A special service will automaticaly load sample datas on applications startup, allowing you to easily play with the project.
TODO : Document
TODO : Document
TODO : Document
TODO : Document
TODO : Document
TODO : Document
TODO That means that simple PR's to TODO can directly make new products of enhance the user experience of all open4goods users.
You will probably need to raise your max map args in order to be able to start elastic
sudo sysctl -w vm.max_map_count=262144
To permanently set the max virtual memory :
- edit /etc/sysctl.conf
- add line vm.max_map_count=262144
- sudo service sysctl restart
After a space crash, elastic indexes are locked. You can get hand back on them by using :
curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_all/_settings -d '{"index.blocks.read_only_allow_delete": null}'