{"id":15136939,"url":"https://github.com/seboste/sapper","last_synced_at":"2026-01-18T02:02:09.569Z","repository":{"id":165930410,"uuid":"561458144","full_name":"seboste/sapper","owner":"seboste","description":"Sapper is a CLI tool written in Go that enables you to rapidly create, extend, and update C++ microservices","archived":false,"fork":false,"pushed_at":"2023-11-06T18:29:11.000Z","size":4325,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T03:45:36.378Z","etag":null,"topics":["cloud-native","cmake","conan","cpp","hexagonal-architecture","microservices","sapper"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seboste.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2022-11-03T18:27:22.000Z","updated_at":"2023-07-25T19:50:03.000Z","dependencies_parsed_at":"2024-09-21T11:01:39.533Z","dependency_job_id":"b19afc13-e835-44c7-b0d1-3e24daa74348","html_url":"https://github.com/seboste/sapper","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/seboste/sapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboste%2Fsapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboste%2Fsapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboste%2Fsapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboste%2Fsapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seboste","download_url":"https://codeload.github.com/seboste/sapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seboste%2Fsapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28526560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cloud-native","cmake","conan","cpp","hexagonal-architecture","microservices","sapper"],"created_at":"2024-09-26T06:41:56.266Z","updated_at":"2026-01-18T02:02:09.554Z","avatar_url":"https://github.com/seboste.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sapper\n\n\u003e **_WARNING:_**  Sapper is still under development. Breaking changes can occur at any time.\n\nSapper is **CLI** tool that enables you to rapidly create, extend, and update **C++ microservices**. It is based on an ever growing template repository --- the **brick** repo --- with a focus on cloud native technology from which you can compose your microservices, e.g.:\n- http and gRPC handler\n- postgreSQL database\n- JWT based authentication\n- docker and kubernetes\n- support for AWS, Azure, and GCP\n- ...\n\n![hexagonal architecture diagram](sapper-animation.gif)\n\n## Foundation\n\nBesides using **C++**, the microservices that can be created with Sapper are constrained by the following:\n\n### Linux AMD64\n\nSapper and the microservices created with it have a built in support for Linux on AMD64. No efforts are planned to support other platforms. On Windows, the usage of [wsl](https://learn.microsoft.com/en-us/windows/wsl/about) is recommended.\n\n### Hexagonal architecture\n\nThe structure of each microservice follows the [hexagonal](https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)) -- aka ports \u0026 adapters -- architecture:\n![hexagonal architecture diagram](sapper-app.png)\n\n| Layer | Desription| Depends on |\n| :------ | :-----| :---- |\n| ports | Domain entities and **interfaces** that the core needs to work with.| - |\n| core | Contains all **business logic** without directly depending on any infrastructure (e.g. databases). | ports |\n| adapters | **Implementation** of the interfaces defined in the ports layer. Adapters should be independent from each other, but often rely on third party libraries. | ports, external libraries|\n| app | The **main** application that brings everything together: Reads configuration, instantiates the core, instantiates the adapters, injects the adapters into the core, calls the handler. | core, adapters |\n\n### Conan package manager\n\nDependencies on 3rd party libraries are managed by the [conan](https://conan.io/) package manager. Thus, each microservices has a *conanfile.txt* in its root folder.\n\n### Make\n\nEach microservice contains a [Unix Makefile](https://www.gnu.org/software/make/manual/make.html) in its root folder that allows to build, test, and deploy the service. Sapper uses the GNU *make* command during some operations. By default [CMake](https://cmake.org/) and [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html#) are used for building and testing a microservice, respectively.\n\n### Microservice-Essentials library\n\nThe [Microservice Essentials](https://github.com/seboste/microservice-essentials) library implements or facilitates the implementation of cross cutting concepts in microservices such as request handling, observability, error handling, and many more. The *cmd* and many of the *adapters* depend on this library, which in turn has no transitive dependencies by design.\n\n## Getting started\n\n1. Make sure that [Conan](https://conan.io/) v1.x, [CMake](https://cmake.org/), [make](https://www.gnu.org/software/make/manual/make.html), and a C++ toolchain (e.g. [clang](https://clang.llvm.org/), [gcc](https://gcc.gnu.org/)) is available in your linux build environment. If that's the case, the following commands run without problems:\n   ```bash\n   conan --version\n   cmake --version\n   make --version\n   gcc --version    #alternative 1\n   clang --version  #alternative 2\n   ```\n   \n3. [Install Go](https://go.dev/doc/install) by e.g. running:\n\n    ```bash\n    wget https://go.dev/dl/go1.20.4.linux-amd64.tar.gz\n    rm -rf /usr/local/go \n    tar -C /usr/local -xzf go1.20.4.linux-amd64.tar.gz\n    export PATH=$PATH:/usr/local/go/bin\n    go version\n    ```\n\n4. Install **Sapper**:\n    ```bash\n    go install github.com/seboste/sapper@latest\n    export PATH=$PATH:~/go/bin\n    sapper version\n    ```\n\n5. Create your first **Sapper** C++ microservice:    \n    ```bash\n    sapper service add my-service\n    cd my-service    \n    sapper brick add handler-http\n    sapper brick add observability-structured-logging\n    sapper brick add repo-in-memory\n    make build\n    ```\n    \u003e **_INFO:_**  hit enter when prompted to specify parameters. It is recommended to execute the commands in a git repository directory and commit the changes after executing each line. In that way, changes made by Sapper can be reconstructed easily.\n\n    The just created service has a http handler that exposes two example REST endpoints, one for setting and one for getting an example entity. Logs are written to standard output in JSON format. The entities are managed in memory by a simple C++ map.\n\n6. Run and test your service:\n   ```bash\n   export LOG_LEVEL=TRACE\n   make run\n   ```\n   The service is now up and running. You can now call the service from a different terminal:\n   ```bash\n   curl -X PUT localhost:8080/Entity/test -H \"Content-Type: application/json\" -d'{\"id\":\"test\",\"string_property\":\"str\",\"int_property\":42}'\n   curl localhost:8080/Entity/test\n   ```\n   An example entity has been stored in and retrieved again from the service. As tracing has been turned on, extensive logs have been written to the console.\n\n7. Add your business code to the core and adapt the ports and adapters to your needs. Voilà, your first C++ microservice is ready.\n\n## Main Features\n\n### Create Microservices\n\nA new Sapper C++ microservice can be created by running the \n```bash \nsapper service add \u003cservicename\u003e\n``` \ncommand. This will create a new directory containing the initial hexagonal microservice structure along with a ``conanfile.txt`` to manage dependencies, a ``CMakeLists.txt``, and a ``Makefile``. Many source files \ninclude code lines that define so called sapper sections:\n```c++\n//\u003c\u003c\u003cSAPPER SECTION BEGIN **SOME_SECTION_NAME**\u003e\u003e\u003e\n...\n//\u003c\u003c\u003cSAPPER SECTION END **SOME_SECTION_NAME**\u003e\u003e\u003e\n```\nSapper uses them to identify code areas that may need to be replaced, merged, appended, or prepended by when adding new sapper bricks to the microservice. Modify them only with caution as it might impede sapper.\n\nYou can build and execute the service with the following commands:\n```bash\ncd \u003cservicename\u003e\nsapper service build .\nmake run\n```\nAs this microservice only contains example ports and a simple example core, the executable returns immediately. You need at least one handler and a repository (aka a DB) for your microservice to do something somewhat meaningful.\n\n### Extend Microservices\n\nNew features (e.g. handlers, databases, notifiers, security, observability, deployment, ...) can be added to a Sapper C++ microservices by adding so called bricks. Use the following command to get a complete list of available bricks including the unique identifier, the version, and a brief description of each brick:\n```bash\nsapper brick list\n```\nThen add the desired brick to your microservice:\n```bash\nsapper brick add \u003cbrickname\u003e\n```\nand enter values for parameters when prompted. New code from the brick library is added to the microservice's codebase (typically by adding another adapter) and integrated into the microservices codebase (typically by adding a few lines of code to the ``main.cpp`` in the ``app`` folder and adding dependencies to 3rd party libs to the ``conanfile.txt``).\n\n\u003e **_INFO:_** Bricks assume that the ports are unchanged by the developer, i.e. the microservice works on that example entity mentioned earlier. Thus, it is recommended to first add the desired bricks to your microservice and then adapt the code to your needs and not the other way around. You can still add bricks later, but adding some of the files may fail and more manual work may be required.\n\n\u003e **_INFO:_** CI ensures that the microservice can be built successfully out of the box when adding a single brick to the initial microservice. However, it is not guaranteed that all possible combinations of bricks can be built successfully (e.g. due to dependency clashes). Some manual fixes may be required.\n\n### Update Dependencies\n\nA regular maintenance task for developers is to update the dependencies. For security reasons and because frequent small increments typically are less error prone and work intense than infrequent big increments, this  task should be done often. Sapper can facilitate this process by running the command\n```bash\nsapper service upgrade .\n```\nIt will build the service, identify which dependencies are not up to date, and then in a bisection method update each dependency until the highest dependency library version is identified for which the build process without code changes is successful.\n\n### Customize Sapper\n\nSapper obtains the brick library from a [github](https://gthub.com) repository. This is [https://github.com/seboste/sapper-bricks](https://github.com/seboste/sapper-bricks) by default. Sapper allows to replace or extend the brick library or replace individual bricks by managing remotes. Call \n```bash \nsapper remote --help\n```\nfor more details. This can for example be useful for organizations that want to provide custom C++ microservice templates to be used by all teams of that organization. Please refer to [https://github.com/seboste/sapper-bricks](https://github.com/seboste/sapper-bricks)'s **README.md** for details on how to create your own Sapper bricks. \n\n\u003e **_INFO:_** Sapper can only be as good as the underlying brick library. If you create bricks that may be useful to the general public, please consider contributing by creating a pull request to [https://github.com/seboste/sapper-bricks](https://github.com/seboste/sapper-bricks).\n\n## Reference\n\nFor a complete description of the commands and subcommands please refer to the tool's help:\n```bash\nsapper --help\nsapper \u003ccommand\u003e --help\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseboste%2Fsapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseboste%2Fsapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseboste%2Fsapper/lists"}