feat: add Devcontainers #2096
feat: add Devcontainers #2096
Conversation
Reviewer's GuideThis PR sets up a fully automated Devcontainer environment by adding a base Dockerfile and devcontainer.json, orchestrating Trustify, Postgres and Keycloak services via docker-compose, providing init and readiness scripts for Keycloak, and including container lifecycle hooks and developer documentation. Sequence diagram for Devcontainer startup and service initializationsequenceDiagram
participant Devcontainer
participant "Keycloak Service"
participant "Keycloak Wait Script"
participant "Keycloak Init Script"
participant "Postgres DB"
participant "Trustify Service"
Devcontainer->>"Keycloak Service": Start Keycloak container
"Keycloak Service"->>"Keycloak Wait Script": Signal ready when HTTP available
"Keycloak Wait Script"->>"Keycloak Init Script": On ready, run initialization
"Keycloak Init Script"->>"Keycloak Service": Configure realm, roles, users, clients
Devcontainer->>"Postgres DB": Start Postgres container
Devcontainer->>"Trustify Service": Start Trustify container
"Trustify Service"->>"Postgres DB": Connect for DB access
"Trustify Service"->>"Keycloak Service": Connect for OIDC authentication
Flow diagram for Keycloak initialization processflowchart TD
start["Start Keycloak container"] --> wait["Run kc-wait.sh (wait for HTTP)"]
wait --> init["Run kc-init.sh (initialize realm)"]
init --> createRealm["Create 'trustd' realm"]
createRealm --> createRole["Create 'admin' role"]
createRole --> createScopes["Create document scopes"]
createScopes --> mapScopes["Map scopes to role"]
mapScopes --> createUser["Create 'admin' user"]
createUser --> setPassword["Set password for user"]
setPassword --> assignRole["Assign 'admin' role to user"]
assignRole --> createClients["Create 'ui' and 'cli' clients"]
createClients --> assignRoleServiceAccount["Assign 'admin' role to cli service account"]
assignRoleServiceAccount --> done["Keycloak ready"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey there - I've reviewed your changes and they look great!
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location> `.devcontainer/keycloak/kc-init.sh:40` </location>
<code_context>
+/opt/keycloak/bin/kcadm.sh create users -r ${TRUSTIFY_REALM} -s username=${TRUSTIFY_USERNAME} -s enabled=true -s firstName="admin" -s lastName="admin" -s email="[email protected]" -o
+/opt/keycloak/bin/kcadm.sh set-password -r ${TRUSTIFY_REALM} --username admin --new-password admin
+
+/opt/keycloak/bin/kcadm.sh add-roles -r ${TRUSTIFY_REALM} --uusername ${TRUSTIFY_USERNAME} --rolename ${TRUSTIFY_ROLE}
+
+# Clients
</code_context>
<issue_to_address>
**issue (typo):** Possible typo in kcadm.sh argument '--uusername'.
Please update '--uusername' to '--username' to ensure correct role assignment.
```suggestion
/opt/keycloak/bin/kcadm.sh add-roles -r ${TRUSTIFY_REALM} --username ${TRUSTIFY_USERNAME} --rolename ${TRUSTIFY_ROLE}
```
</issue_to_address>
### Comment 2
<location> `.devcontainer/Dockerfile:3-4` </location>
<code_context>
+FROM mcr.microsoft.com/devcontainers/base:ubuntu
+
+RUN sudo apt update && \
+ sudo apt install -y build-essential pkg-config libssl-dev postgresql-client
</code_context>
<issue_to_address>
**suggestion:** Using 'sudo' in Dockerfile may be unnecessary.
Since Dockerfile commands are executed as root by default, 'sudo' can be removed to streamline the build and prevent complications if the user context changes in the base image.
</issue_to_address>
### Comment 3
<location> `.devcontainer/README.md:27` </location>
<code_context>
+
+Install the extension https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
+
+Only if you use podman, thefore Optional:
+
+Go to the Extension Settings:
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'thefore' should be 'therefore'.
Change 'thefore' to 'therefore' to improve readability.
```suggestion
Only if you use podman, therefore Optional:
```
</issue_to_address>
### Comment 4
<location> `.devcontainer/README.md:35` </location>
<code_context>
+- `Dev › Containers: Docker Path` set `podman`
+- `Dev › Containers: Docker Socket Path` set `/run/podman/podman.sock`
+
+To open the repository with DevContainers do `Ctrl + Shift + P` and enter `Dev Containers: Rebuild and Reopen in Container` or `Dev Containers: Reopen in Container`. For more options see the Extension documentations.
</code_context>
<issue_to_address>
**suggestion (typo):** Use 'documentation' instead of 'documentations'.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| /opt/keycloak/bin/kcadm.sh create users -r ${TRUSTIFY_REALM} -s username=${TRUSTIFY_USERNAME} -s enabled=true -s firstName="admin" -s lastName="admin" -s email="[email protected]" -o | ||
| /opt/keycloak/bin/kcadm.sh set-password -r ${TRUSTIFY_REALM} --username admin --new-password admin | ||
|
|
||
| /opt/keycloak/bin/kcadm.sh add-roles -r ${TRUSTIFY_REALM} --uusername ${TRUSTIFY_USERNAME} --rolename ${TRUSTIFY_ROLE} |
There was a problem hiding this comment.
issue (typo): Possible typo in kcadm.sh argument '--uusername'.
Please update '--uusername' to '--username' to ensure correct role assignment.
| /opt/keycloak/bin/kcadm.sh add-roles -r ${TRUSTIFY_REALM} --uusername ${TRUSTIFY_USERNAME} --rolename ${TRUSTIFY_ROLE} | |
| /opt/keycloak/bin/kcadm.sh add-roles -r ${TRUSTIFY_REALM} --username ${TRUSTIFY_USERNAME} --rolename ${TRUSTIFY_ROLE} |
| RUN sudo apt update && \ | ||
| sudo apt install -y build-essential pkg-config libssl-dev postgresql-client |
There was a problem hiding this comment.
suggestion: Using 'sudo' in Dockerfile may be unnecessary.
Since Dockerfile commands are executed as root by default, 'sudo' can be removed to streamline the build and prevent complications if the user context changes in the base image.
carlosthe19916
force-pushed
the
feat/devcontainers
branch
from
42623fe to
239a8b0
Compare
|
I like the idea. To make things easier, I don't think you need either keycloak or postgres. You can use the embedded OIDC issuer and the embedded postgres database. Former should be active by default when using |
Signed-off-by: Carlos Feria <[email protected]>
carlosthe19916
force-pushed
the
feat/devcontainers
branch
from
239a8b0 to
8959642
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2096 +/- ##
==========================================
+ Coverage 68.03% 68.17% +0.14%
==========================================
Files 367 368 +1
Lines 20590 20682 +92
Branches 20590 20682 +92
==========================================
+ Hits 14008 14100 +92
+ Misses 5746 5741 -5
- Partials 836 841 +5 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Although I do see the value in the embedded OIDC, In my daily routine I do rely in tools like Keycloak. When it comes to integration with other tools like the UI having something like Keycloak that allows me to go deep in configuration is very important. What about having both? I believe Devcontainer allow the definition of multiple setups that can coexist together.
This way we both have what we need. What do you think? Does it seems like a fair compromise for both types of users? |
Signed-off-by: Carlos Feria <[email protected]>
|
I added a commit that add both, the required minimal Devcontainer and also a full one. Now when users want to setup their development environment they will be asked which one they want: 
|
Signed-off-by: Carlos Feria <[email protected]>
ctron
left a comment
ctron
left a comment
There was a problem hiding this comment.
I like the idea of having both. Thanks for that.
I just tried it out, but it doesn't seem to work. At least for me. Working on a mac today, I had to switch VScode dev container to podman first. Then it starts, but I can't connect to the frontend. I says "connection refused" in the logs.
|
@ctron thanks for the review... I'll be out for 1 week but I'll look into it as soon as I am back. |
|
@ctron I have done an additional test to the
Note: devcontainers map ports to the host machine, in the case of the
Maybe your port 8080 was mapped to a different port in your host machine therefore you were not able to open http://localhost:8080 ? 
Screencast.From.2025-11-18.10-03-27.mp4 |
|
So I did the following:
What I can see is:
I am not aware of anything else running on port 8080. I'd assume I'd see a page loading in that case. |
|
@ctron Devcontainers and Vscode map the container port to the host and it does not necessarily use the same port in the container and in the host. Likely your 8080 port is not being mapped to 8080 in your host OS. That is how it works devcontainers. Most of the time it will map the same ports in the host and in the container but sometimes it won't. In the image below, the 8080 port has been mapped to 8081 in my host OS. So if I open http://localhost:8081 it will work. 
|
|
Here is what I see: Listening on port 8080 is only VScode: Exiting VScode, those listening sockets are gone. |
|
@ctron I have tested it in a 100% clean OS and I did find issues with forwarding the container port that belongs to the embedded oidc. I made it work making this change in the source code: Before: trustify/server/src/embedded_oidc.rs Lines 75 to 78 in 108506e After: server
.base(base)
.port(port)
.bind(std::net::IpAddr::V6(Ipv6Addr::UNSPECIFIED))
.add_issuer(name.to_string(), issuer)?;The problem being that the embedded oidc exposes its service through http://[::1] hence not allowing mapping between the container and the OS. Not sure if that is the problem you are facing though. |
|
|
||
| ### Podman | ||
|
|
||
| Start Podman service for a regular user (rootless) and make it listen to a socket: |
There was a problem hiding this comment.
This should be scoped to "Linux", it works differently on Windows and MacOS, right?
There was a problem hiding this comment.
Yes, Windows and MacOS have to use "Podman Machine" if am not wrong.
I have no MacOS neither Windows for me to be able to write accurate instructions. I expect the README to evolve and be enhanced title by title by Windows and MacOS users if they find DevContainer within VSCode useful.
There was a problem hiding this comment.
I'm against having half-done instructions. If we can't come up with a solution which works on all platforms, including documentation, then it might better to not do it. Maybe someone with more Mac OS/Windows experience can amend this PR.
There was a problem hiding this comment.
Consider this PR as a well intended contribution to a community project.
If we could merge this PR it would help me a lot as it will allow me to save a ton of time as a regular code watcher of this repository.
I guess the majority of contributors of this repository are Windows and MacOS users and very few of them use Linux.
It is not my intention to make the core contributors harder. Unfortunately I have no way of testing things on MacOS nor Windows and be sure that the instructions are accurate.
I was expecting an "evolution" approach, evolve documentation in the same peace as users start using it. There is low risk as it does not affect the code in any way. But if the approach "all or nothing" is the approach advised by the core contributors of this project then I am afraid I cannot anything about it so please feel free to close this PR.
There was a problem hiding this comment.
As a side note. This PR added a README for setting up Devcontainers with good intentions, but it brought more troubles than expected so maybe it is just better to delete the README.md inside the .devcontainer directory. Documenting how to set up podman or docker is something out of the scope of any project.
Here are some examples of relatively big projects that use devcontainers. None of them have docs for setting up Podman/Docker:
There was a problem hiding this comment.
I guess […] Unfortunately I have no way of testing things on MacOS nor Windows and be sure that the instructions are accurate.
I understand, but then I don't want to merge this. If we end up with instructions that only work for part of users, that will cause frustration, because things don't work.
I am sure you can find someone with MacOS and collaborate. What would at least sort out least two out of three.
If that's not possible, then I'm against merging this.
2 participants
Devcontainers is kinda a standard way of setting up development environments so we guarantee a solid, reliable, and automated way of setting up dependencies.
This PR adds Devcontainers and includes:
libssl-devandpostgres-clientcargo run --bin trustd apishould be all you need.This PR also includes a video demo under the directory
.devcontainer/assets/demo.mp4Note: I have encounter an issue with executing
AUTH_DISABLED=true cargo run --bin trustdwhich enables the Postgresql database in from the filesystem:error=Connection Error: pool timed out while waiting for an open connection: pool timed out while waiting for an open connection: pool timed out while waiting for an open connection database=DatabaseI ignore the reason but I believe having the database in a container as described by the docker-compose.yaml included in this PR should be a better way of representing a real environmentEDIT: As an additional note, this should allow users to run Codespaces from Github. There are other tools around Devcontainers like DevPod among others. So I hope this could help new comers to this repo to quickly setup their environments and start playing with the code
Summary by Sourcery
Set up a reproducible development environment using Devcontainers, including automated provisioning of OS dependencies, Postgres database, and Keycloak authentication service
New Features:
Enhancements:
Documentation: