Extending & Modifying RavenDB Dockerfile
Some custom setups solutions may lead you to a necessity of building over our Dockerfile, or even customizing it. This article explains in detail, how it works.
For detailed Dockerfile guide, visit Containers > Dockerfile > Overview
Extending the Existing ravendb/ravendb
Image
This approach involves using FROM ravendb/ravendb
to build upon the official image, adding custom commands, scripts, or configurations.
Why Should I Extend the RavenDB Dockerfile?
- Simple customization: Ideal for small, incremental changes that do not require rebuilding the entire image from scratch.
- Keeps RavenDB's default behavior: Build on top of the existing official
ravendb/ravendb
image while preserving core functionality. - Customization of startup scripts: Provides flexibility to replace the
run-raven.sh
startup script with a custom, more focused version tailored to your deployment needs.
Dockerfile Example for Extension
# Use the official RavenDB image as the base
FROM ravendb/ravendb:7.0-ubuntu-latest
# Add your custom script or commands
COPY my-script.sh /usr/lib/ravendb/scripts/my-script.sh
RUN chmod +x /usr/lib/ravendb/scripts/my-script.sh
# Add an environment variable
ENV MY_CUSTOM_VAR="MyValue"
# Customize the HEALTHCHECK
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8080 || exit 1
# Replace the CMD (optional!)
COPY my-run-raven.sh /usr/lib/ravendb/scripts/run-raven.sh
CMD ["/bin/bash", "/usr/lib/ravendb/scripts/run-raven.sh"]
Building for Multiple Platforms
Use BuildX if you need to build for multiple architectures (e.g., x64, arm64):
docker buildx build --platform linux/amd64,linux/arm64 -t my-ravendb .
Tips
You can:
- Add scripts that configure or extend RavenDB's behavior (e.g., preloading data or setting specific configurations). Ensure scripts are executable (chmod +x).
- Pass custom values or configurations via ENV directives or at runtime using docker run -e.
- Customize HEALTHCHECK to match your deployment’s requirements, ensuring RavenDB is responding as expected.
Customizing the RavenDB Dockerfile
If your use case requires more extensive customization, you can modify the Dockerfile directly to create a tailored image.
Possibilities of modifications
Change the Base Image
Replace FROM mcr.microsoft.com/dotnet/runtime-deps:8.0-jammy
with another OS, such as debian:buster
or alpine:latest
.
However, make sure to select one that includes .NET runtime dependencies or install them on your own.
Add Custom Dependencies
Use RUN
commands to install additional dependencies specific to your environment.
Customize Environment Variables
Adjust ENV
declarations to preconfigure RavenDB settings, such as data directories or logs.
You can do the same thing in Docker using -e
argument without tinkering with the Dockerfiles, but may want to have this fixed in the image.
Replace the Entry Script
Copy and use a custom run-raven.sh
script:
COPY my-run-raven.sh /usr/lib/ravendb/scripts/run-raven.sh
CMD ["/bin/bash", "/usr/lib/ravendb/scripts/run-raven.sh"]
Entry Script (run-raven.sh)
This script initializes and runs the RavenDB server. It's designed to work for anyone, so in some scenarios you may want to chisel it down a bit, modify, or completely replace, which we'll cover next. Key responsibilities include:
Legacy Data Migration
/usr/lib/ravendb/scripts/link-legacy-datadir.sh
This script was created to handle legacy data volumes, that were working with RavenDB before 6.0. The data had different directory structure inside Linux back then, so we needed to migrate them properly after update to 6.0+.
Command Construction
Constructs the RavenDB server start command using arguments and environment variables:
COMMAND="/usr/lib/ravendb/server/Raven.Server"
Certificate Checks
Ensures proper certificate configuration for secure HTTPS connections.
Startup Environment Setup
Configures the RAVEN_ServerUrl
environment variable if not already set.
Graceful Shutdown
Handles termination signals to cleanly stop the server.
Database Auto-Creation
Calls a utility script to create the database if the RAVEN_DATABASE
environment variable is set.
Replacing run-raven.sh
Replacing allows full control of the startup process for both extending and modifying approaches. The only requirement is that the script must ultimately run the RavenDB server. Everything else is optional and can be customized to fit your specific needs. Some ideas include:
Certificates management
Retrieve and configure SSL certificates, such as from a secure vault or web server.
Exports Environment Variables
Define and set variables like RAVEN_ServerUrl
to match your deployment requirements.
Handles Shutdown Gracefully
Use signal trapping for smooth termination of the server:
trap 'kill -TERM "$COMMANDPID"' TERM INT
Custom Operations
Add database initialization or additional setup scripts as needed.
Example Custom Script
# Custom startup script for RavenDB
echo "Starting custom RavenDB setup..."
# Get and configure certificates
get_certificates() {
# Implement logic to retrieve certificates, e.g., from a web server or secured vault
}
check_for_certificates
# Start RavenDB
COMMAND="/usr/lib/ravendb/server/Raven.Server -c /etc/ravendb/settings.json"
$COMMAND &
COMMANDPID=$!
# Handle shutdown gracefully
trap 'kill -TERM "$COMMANDPID"' TERM INT
wait $COMMANDPID