📍

Mentorship

Learn GeoServer development through hands-on mentorship. Start with Docker setup, tackle beginner-friendly issues, and grow your skills incrementally with the Kaizen philosophy.

GeoGuru.Africa offers mentorship for developers who want to contribute to GeoServer. Whether you’re new to open source or looking to deepen your expertise, we guide you through the journey from first contribution to sustained impact.

Getting Started with Docker Development Environment

The fastest way to start contributing to GeoServer is using the DevDocker environment - a pre-configured containerized development setup that gets you coding in minutes, not hours. This is the recommended approach for all GeoGuru participants.

Why DevDocker?

Traditional GeoServer development requires installing and configuring multiple tools: Java JDK, Maven, Git, Tomcat, and more. Getting all these tools working together can take hours or even days, especially if you encounter version conflicts or platform-specific issues.

DevDocker eliminates this setup friction by providing:

  • Pre-configured build tools: JDK 21, Maven 3.8+, Git - all versions tested and working
  • IDE connectivity: Connect your favorite IDE (Kiro, VSCode, IntelliJ) via SSH
  • Remote debugging: Set breakpoints and debug GeoServer live with JDWP
  • Fast builds: Optimized Maven caching means 2-3 minute builds after the first run
  • Production parity: Environment mirrors the official GeoServer Docker image structure

Time to first contribution: 15-20 minutes from zero to running GeoServer with your first code change.

Prerequisites

Before starting, ensure you have:

  • Docker Desktop (Windows/Mac) or Docker Engine (Linux) - Install Docker
  • Docker Compose 2.0+ (usually included with Docker Desktop)
  • SSH client (built into Windows 10+, macOS, and Linux)
  • GitHub account (free) - Sign up here
  • Basic command-line familiarity (navigating directories, running commands)

System Requirements:

  • 8GB RAM minimum (16GB recommended for comfortable development)
  • 20GB free disk space (for Docker images and Maven dependencies)
  • Internet connection (for initial setup and dependency downloads)

Quick Start: Your First 20 Minutes

Follow these steps to go from zero to running GeoServer with your own fork. Commands shown with $ are run on your host machine, commands with # are run inside the container.

Step 1: Fork GeoServer on GitHub (2 minutes)

  1. Navigate to https://github.com/geoserver/geoserver
  2. Click the “Fork” button in the top-right corner
  3. Select your GitHub account as the destination
  4. Wait for GitHub to create your fork (usually takes 30-60 seconds)

Step 2: Get DevDocker (3 minutes)

Clone the DevDocker repository and start the environment:

$ git clone https://github.com/geoguru-africa/DevDocker.git
$ cd DevDocker
$ docker-compose up -d

Verify it’s running:

$ docker ps

You should see devdocker in the list of running containers.

Step 3: Set Up SSH Access (2 minutes)

Run the SSH setup utility:

$ ./scripts/setup-ssh-keys.sh

This script will:

  • Detect your existing SSH keys
  • Let you select which key to use
  • Configure the container for SSH access

Then connect to the container:

$ ssh -p 2222 root@localhost

You’ll see a prompt like # (inside the container)

Step 4: Clone Your Fork (5 minutes)

Inside the container:

# git clone https://github.com/YOUR_USERNAME/geoserver.git
# cd geoserver

Configure upstream remote:
# git remote add upstream https://github.com/geoserver/geoserver.git
# git fetch upstream --tags

Either: checkout a recent release
# git checkout 2.28.2

Or: stick with main for cutting-edge development
# git checkout main

Step 5: Build GeoServer (10-15 minutes first time, 2-3 minutes after)

# build-geoserver.sh

Note: The first build will download all required dependencies, which typically takes 10-15 minutes depending on your internet connection. After the initial build, Maven caches these dependencies locally, so subsequent builds complete much faster in just 2-3 minutes.

Step 6: Start GeoServer (1 minute)

# start-geoserver.sh

Wait for startup (usually 30-60 seconds). You’ll see: “Server startup in [X] milliseconds”

Step 7: Access GeoServer (1 minute)

Open your browser and navigate to:

You should see the GeoServer web interface with demo layers and sample data.

Congratulations! You now have a fully functional GeoServer development environment. You’re ready to make your first contribution.

Making Your First Code Change

Let’s make a simple change to verify your development workflow.

1. Find a file to modify

# cd /workspace/geoserver
# nano src/web/app/src/main/webapp/index.html

Note: The container includes nano (a beginner-friendly text editor). Use Ctrl+O to save, Ctrl+X to exit.

2. Make a small change

Add a comment or change some text in the HTML file. For example, add:

<!-- Modified by [Your Name] for GeoGuru mentorship -->

3. Rebuild the web application

# build-geoserver.sh

This takes about 1-2 minutes.

4. Restart GeoServer

# restart-geoserver.sh

5. Verify your change

Refresh http://localhost:8080/geoserver in your browser. View the page source to see your comment.

6. Commit and push

# cd /workspace/geoserver
# git add src/web/app/src/main/webapp/index.html
# git commit -m "Add mentorship comment to welcome page"
# git push origin main

You’ve just completed the full development cycle: edit → build → test → commit → push. This is the workflow you’ll use for all contributions.

Connecting Your IDE

While you can edit files via SSH using vim or nano, most developers prefer using their IDE. DevDocker supports remote development with popular IDEs.

Option 1: VSCode (Recommended)

VSCode provides excellent remote development support via SSH:

1. Install Remote-SSH extension:

  • Open VSCode
  • Press Ctrl+Shift+X (Extensions)
  • Search for “Remote - SSH”
  • Click Install

2. Configure SSH connection:

Run the SSH config setup utility on your host:

$ ./scripts/setup-ssh-config.sh

This script will:

  • Detect your SSH keys
  • Let you select which key to use
  • Create or update your ~/.ssh/config file

3. Connect:

  • Press Ctrl+Shift+P (Command Palette)
  • Type “Remote-SSH: Connect to Host”
  • Select “devdocker”
  • A new window opens connected to the container

4. Open workspace:

  • File → Open Folder
  • Navigate to /workspace/geoserver
  • Click OK

You now have full IDE access with syntax highlighting, code completion, and integrated terminal.

Option 2: Kiro IDE

Follow the same steps as VSCode (Kiro uses the same Remote-SSH extension).

Option 3: IntelliJ IDEA

  1. Go to File → Settings → Build, Execution, Deployment → Deployment
  2. Add new SFTP server:
    • Host: localhost
    • Port: 2222
    • User: root
  3. Map remote path /workspace/geoserver to local project

Remote Debugging

DevDocker includes full debugging support via JDWP (Java Debug Wire Protocol). This lets you set breakpoints, inspect variables, and step through code while GeoServer is running.

Setting up debugging in VSCode/Kiro:

1. Create debug configuration:

Create .vscode/launch.json in your workspace:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Debug GeoServer",
      "request": "attach",
      "hostName": "localhost",
      "port": 5005
    }
  ]
}

2. Start GeoServer (if not already running):

# start-geoserver.sh

3. Attach debugger:

  • Press F5 or click Run → Start Debugging
  • You should see “Debugger attached” in the debug console

4. Set a breakpoint:

  • Open a Java file (e.g., src/main/src/main/java/org/geoserver/GeoServerApplication.java)
  • Click in the left margin next to a line number to set a breakpoint (red dot appears)

5. Trigger the breakpoint:

  • Access GeoServer in your browser (http://localhost:8080/geoserver)
  • When code execution hits your breakpoint, the debugger pauses
  • You can inspect variables, step through code, and evaluate expressions

Hot Code Replacement: For simple method body changes, you can modify code while debugging and the changes take effect immediately without restarting GeoServer. For structural changes (new methods, fields, classes), you’ll need to rebuild and restart.

Understanding the Development Workflow

Now that you have everything set up, here’s the typical development workflow. Commands with $ are on your host, commands with # are inside the container.

1. Find an issue to work on

Browse the GeoServer issue tracker:

2. Create a feature branch

Inside the container:

# cd /workspace/geoserver
# git checkout main
# git pull upstream main
# git checkout -b fix/issue-1234-description

3. Make your changes

Edit code using your IDE or SSH. Test locally by:

4. Write tests

GeoServer requires tests for most contributions:

# cd /workspace/geoserver/src
# mvn test -pl main

5. Commit and push

# git add .
# git commit -m "Fix issue #1234: Description of fix"
# git push origin fix/issue-1234-description

6. Create Pull Request

  1. Navigate to your fork on GitHub
  2. Click “Compare & pull request”
  3. Fill in the PR description:
    • What issue does this fix?
    • What changes did you make?
    • How did you test it?
  4. Submit to the upstream repository

7. Respond to feedback

Maintainers will review your PR and may request changes. Make updates:

# git add .
# git commit -m "Address review feedback"
# git push origin fix/issue-1234-description

The PR updates automatically when you push to your branch.

Common Development Tasks

All commands below are run inside the container (with # prompt):

Rebuild after code changes:

# cd /workspace/geoserver/src
# mvn install -T 2C

Or rebuild specific module (faster):
# mvn install -T 2C -pl web/app -am

Restart GeoServer:

# restart-geoserver.sh

View GeoServer logs:

On host:
$ docker logs -f devdocker

Or inside container:
# tail -f /usr/local/tomcat/logs/catalina.out

Run tests:

# cd /workspace/geoserver/src

Run all tests (slow - 30+ minutes):
# mvn test

Run tests for specific module:
# mvn test -pl main

Run specific test class:
# mvn test -pl main -Dtest=GeoServerApplicationTest

Update your fork:

# cd /workspace/geoserver
# git checkout main
# git pull upstream main
# git push origin main

Work with specific GeoServer version:

List available versions:
# git tag -l | grep "^2\." | sort -V | tail -20

Checkout specific version:
# git checkout 2.28.2

Or create branch from version:
# git checkout -b my-feature-2.28.2 2.28.2

Troubleshooting

If you encounter issues during setup or development, refer to the comprehensive troubleshooting guide in the DevDocker repository:

  • In the cloned repository: See README.md Troubleshooting section
  • Online: Visit the DevDocker GitHub repository for the latest troubleshooting tips

Common issues covered include:

  • SSH connection problems
  • Port conflicts
  • Build failures
  • Memory issues
  • Git clone interruptions
  • GeoServer startup problems

Advanced: Multi-Project Development

If you need to modify GeoTools or GeoWebCache (GeoServer’s dependencies), DevDocker supports multi-project development:

1. Clone additional repositories (inside container):

# cd /workspace
# git clone https://github.com/YOUR_USERNAME/geotools.git
# git clone https://github.com/YOUR_USERNAME/geowebcache.git

2. Configure custom builds (on host):

Edit .env file:

CUSTOM_GEOTOOLS=true
CUSTOM_GEOWEBCACHE=true

3. Restart container (on host):

$ docker-compose restart

4. Build all projects (inside container):

# build-geotrio.sh

This builds GeoTools → GeoWebCache → GeoServer in the correct order, using your local changes.

Note: Multi-project builds take significantly longer (30+ minutes first time). Only enable this if you’re specifically working on GeoTools or GeoWebCache integration.

Technical Focus Areas

Our mentorship program emphasizes key areas where GeoServer needs ongoing development:

Docker Development Environment

  • Setting up reproducible dev environments
  • Creating custom Docker images for testing
  • Optimizing container builds for faster iteration

Custom Builds

  • Building GeoServer from source
  • Creating custom distributions with specific extensions
  • Managing dependencies and build configurations

Community Modules

  • Developing new community modules
  • Testing and documenting community extensions
  • Contributing to the community module ecosystem

GitHub Actions and CI/CD

  • Improving automated testing pipelines
  • Adding new test scenarios
  • Optimizing build times and resource usage
  • Contributing to continuous integration infrastructure

Security

  • Identifying and fixing security vulnerabilities
  • Implementing security best practices
  • Contributing to security documentation
  • Participating in security reviews and audits

These focus areas represent ongoing needs in the GeoServer project. Whether you’re interested in infrastructure, security, or feature development, there’s a place for your contributions.

Next Steps: Your Contribution Journey

Now that you have a working development environment, here’s your path forward:

Week 1-2: Familiarization

  • Explore the GeoServer web interface
  • Read the GeoServer Developer Guide
  • Browse the codebase in your IDE
  • Make small experimental changes to understand the build process

Week 3-4: First Contribution

  • Find a “good first issue” on GitHub
  • Start with documentation improvements or small bug fixes
  • Submit your first Pull Request
  • Respond to maintainer feedback

Month 2-3: Build Expertise

  • Tackle more complex issues
  • Write tests for existing functionality
  • Contribute to community modules
  • Help other developers with setup questions

Month 4+: Sustained Impact

  • Take on feature development
  • Review other contributors’ PRs
  • Mentor new contributors
  • Consider joining the GeoServer community as a regular contributor

Remember: Every expert contributor started exactly where you are now. The key is consistent, incremental progress. Small contributions build trust and familiarity with the codebase.

Getting Help

If you encounter issues or have questions:

1. Check existing documentation:

2. Search for similar issues:

3. Ask the community:

4. Contact GeoGuru mentorship:

  • Email: info@geoguru.africa
  • Tell us about your issue, what you’ve tried, and where you’re stuck
  • We’re here to help you succeed

Why This Matters

Contributing to GeoServer isn’t just about writing code - it’s about joining a global community of developers working on critical geospatial infrastructure. Your contributions help:

  • Organizations worldwide: GeoServer powers mapping applications for governments, NGOs, and businesses
  • Open source ecosystem: Your work benefits the entire geospatial community
  • Your career: Open source contributions demonstrate real-world skills to employers
  • Future contributors: Your improvements make it easier for the next generation

The DevDocker environment removes technical barriers so you can focus on what matters: learning, contributing, and growing as a developer.

The Kaizen Philosophy

We follow the Japanese Kaizen philosophy of continuous, incremental improvement. You don’t need to make massive contributions to have impact. Start small, build trust, and grow your involvement over time.

The Journey:

  1. Start with documentation - Fix a typo, clarify a confusing section, add an example
  2. Build familiarity - As you read the docs, you’ll understand the architecture better
  3. Tackle small bugs - Fix issues you encounter while learning the system
  4. Contribute features - Once you understand the patterns, add new capabilities
  5. Volunteer for the unglamorous work - Take on the big, scary, audacious tasks that no one wants to touch - the dirty behind-the-scenes work that keeps projects healthy but rarely gets celebrated
  6. Mentor others - Share what you’ve learned to help the next generation of contributors

This path mirrors Peter Smythe’s journey from FOSS4G Tanzania 2018 to GeoServer PSC member. It starts with curiosity and grows through consistent, quality contributions.

Welcome to the GeoServer community. We’re excited to see what you’ll build.

Resources

How to Get Mentored

Ready to start your GeoServer contribution journey? We’re here to guide you.

Contact us: info@geoguru.africa

Tell us about your background, what you want to learn, and how much time you can commit. We’ll match you with resources, suggest starting points, and provide ongoing support as you grow your skills.

Mentorship is free. Our goal is to build a stronger, more diverse GeoServer community by removing barriers and bringing knowledge to developers across Africa and beyond.

🌍

Explore More

🎓

Get Mentored

Learn GeoServer development with hands-on guidance

Learn more
💚

Support the Fund

Help African developers attend FOSS4G conferences

Learn more