Development Workflow¶
This guide explains the full development cycle for contributing to Security Shepherd.
Prerequisites¶
Check the To contribute column of the prerequisites before you start.
1. Create Your Branch¶
Fork the repository or create a branch from the dev branch:
Branch naming convention: dev#<issueNumber> (e.g., dev#536). If an issue needs more than one pull request, add a short suffix (e.g., dev#1070-sso).
2. Make Your Changes¶
Edit the code in your branch. Key directories:
src/main/java/- Java source codesrc/main/webapp/- Web resources (JSP, CSS, JS)src/test/java/- Unit tests
3. Build the WAR¶
Build the application with Maven:
This generates:
- The WAR file in target/
- HTTPS certificates for Docker
Each Maven command runs every step before it, so install includes verify, and verify includes package:
| Step | What it does in this project | package |
verify |
install |
|---|---|---|---|---|
validate |
Checks the Maven version and dependency signatures; with -Pdocker, copies the SQL and Mongo scripts |
✅ | ✅ | ✅ |
generate-sources |
With -Pdocker, uncomments DELIMITER in the SQL scripts |
✅ | ✅ | ✅ |
compile |
Compiles the code for Java 17 | ✅ | ✅ | ✅ |
test |
Runs unit tests | ✅ | ✅ | ✅ |
package |
Builds target/owaspSecurityShepherd.war |
✅ | ✅ | ✅ |
integration-test |
Runs integration tests | — | ✅ | ✅ |
verify |
Runs the Spotless format check | — | ✅ | ✅ |
install |
Copies the WAR into your local Maven cache, ~/.m2 |
— | — | ✅ |
package works on JDK 17 or newer. verify and install need JDK 17, because they run the Spotless format check, which fails on JDK 25 or newer.
-DskipTests skips the two test steps, but not Spotless.
4. Test in Runtime Environment¶
Start the full application stack using Docker Compose:
# Build and start all containers (MariaDB, MongoDB, Tomcat)
docker compose up --build
# Or run in detached mode
docker compose up -d --build
The Tomcat image installs the Ubuntu security updates released since its base image was published. Docker caches the base image and that build step, so --build can reuse an old base image and old packages. Before testing or scanning an image, for example for a release, rebuild it without the cache:
Access the application: - HTTP: http://localhost - HTTPS: https://localhost:8443
Default login credentials:
- Username: admin
- Password: password
Viewing Logs¶
Rebuilding After Code Changes¶
After making additional changes:
# Rebuild the WAR
mvn -Pdocker clean install -DskipTests
# Rebuild and restart only the web container
docker compose up -d --build web
Stopping the Environment¶
To also remove volumes (database data):
5. Run Automated Tests¶
See testing.md for instructions on running the unit and integration test suite.
6. Submit Your Pull Request¶
When your changes are complete and tests pass:
- Push your branch to your fork/origin
- Create a Pull Request targeting the
devbranch - Ensure all CI checks pass
See CONTRIBUTING.md for code formatting and PR guidelines.
Environment Configuration¶
The .env file in the project root contains environment variables for Docker. Key variables:
| Variable | Description |
|---|---|
DB_PASS |
MariaDB root password |
HTTP_PORT |
HTTP port (default: 80) |
HTTPS_PORT |
HTTPS port (default: 8443) |
Troubleshooting¶
Container Won't Start¶
Check if ports are already in use:
Database Connection Issues¶
Ensure the database container is healthy:
Changes Not Reflected¶
Make sure you rebuilt both the WAR and the container: