From 6ccd2142c5996a472a935d4016df3eea66f3a040 Mon Sep 17 00:00:00 2001 From: james-burgess Date: Tue, 30 Sep 2025 10:55:36 +0200 Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=AA=9A=20Docker=20and=20docker=20comp?= =?UTF-8?q?ose=20setup=20for=20local=20development?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Docker image now builds the war file as a build stage so devs dont need java installed. - Full compose setup to run all services - replace smtp with mailhog for local emails --- .dockerignore | 2 + Dockerfile | 78 ++++++++++ .../tomcat/jdoconfig.properties.template | 27 ++++ .../.dockerfiles/tomcat/wildbook-start.sh | 37 +++++ docker-compose.yml | 144 ++++++++++++++++++ frontend/maven-build.sh | 11 +- 6 files changed, 295 insertions(+), 4 deletions(-) create mode 100644 .dockerignore create mode 100644 Dockerfile create mode 100644 devops/development/.dockerfiles/tomcat/jdoconfig.properties.template create mode 100644 devops/development/.dockerfiles/tomcat/wildbook-start.sh create mode 100644 docker-compose.yml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000000..4ee9c6e6ef --- /dev/null +++ b/.dockerignore @@ -0,0 +1,2 @@ +logs/ +wildbook-data/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..3ae99db384 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,78 @@ +# Stage 1: Build Wildbook WAR +FROM maven:3.9.6-eclipse-temurin-21 AS build + +# Install build-essential, Node.js and npm +# build-essential is needed for some native npm modules +RUN apt-get update && \ + apt-get install -y build-essential curl gnupg && \ + curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && \ + apt-get install -y nodejs imagemagick rsync && \ + apt-get clean && rm -rf /var/lib/apt/lists/* + +# Set working directory to the application root +WORKDIR /app + +COPY local-repo /app/local-repo + +# Copy pom.xml and download Maven dependencies +COPY pom.xml ./ +RUN mvn verify clean --fail-never + +COPY ./frontend /app/frontend +COPY ./src/main/webapp/javascript /app/src/main/webapp/javascript + +WORKDIR /app/frontend +ENV PUBLIC_URL=/react/ +ENV SITE_NAME="Wildbook" +RUN npm install react-app-rewired +RUN npm ci +RUN npm run build +RUN mkdir -p /app/src/main/webapp/react && rsync -a ./build/ /app/src/main/webapp/react/ + +WORKDIR /app +COPY . . +# Build the WAR file, skipping tests and front end build for faster build +ENV SKIP_FRONTEND_BUILD=true +RUN mvn -T 4 clean install -DskipTests -Dmaven.antrun.skip=true + + +# Stage 2: Deploy to Tomcat +FROM tomcat:9.0.113-jre17-temurin-jammy + +# Install envsubst for environment variable substitution +RUN apt-get update && apt-get install -y gettext-base imagemagick && rm -rf /var/lib/apt/lists/* + + +# Create staging location for config files (seeded into mounted volume at runtime) +RUN mkdir -p /opt/wildbook_seed/WEB-INF/classes/bundles + +# Create empty AnnotationLiteCache.json file with valid JSON to prevent startup warning +# RUN echo '{}' > /usr/local/tomcat/webapps/wildbook_data_dir/WEB-INF/AnnotationLiteCache.json + +# Set environment variables for runtime configuration +ENV JAVA_OPTS="-Djava.awt.headless=true -Xms4096m -Xmx4096m" + +# Copy config and bundle files to staging location (seeded into mounted volume at runtime) +COPY --from=build /app/src/main/resources/bundles/ /opt/wildbook_seed/WEB-INF/classes/bundles/ + +# Copy Docker-specific configuration files to staging +COPY ./devops/development/.dockerfiles/tomcat/server.xml /usr/local/tomcat/conf/server.xml +COPY ./devops/development/.dockerfiles/tomcat/watermark.png /usr/local/tomcat/watermark.png +COPY ./devops/development/.dockerfiles/tomcat/IA-wbia.json /opt/wildbook_seed/WEB-INF/classes/bundles/IA.json +COPY ./devops/development/.dockerfiles/tomcat/IA-wbia.properties /opt/wildbook_seed/WEB-INF/classes/bundles/IA.properties +COPY ./devops/development/.dockerfiles/tomcat/commonConfiguration.properties /opt/wildbook_seed/WEB-INF/classes/bundles/commonConfiguration.properties +COPY ./devops/development/.dockerfiles/tomcat/jdoconfig.properties.template /opt/wildbook_seed/WEB-INF/classes/bundles/jdoconfig.properties.template + + +# Copy the built WAR file from the build stage to Tomcat's webapps directory as ROOT.war +COPY --from=build /app/target/wildbook-*.war /usr/local/tomcat/webapps/ROOT.war + +# Copy startup script +COPY ./devops/development/.dockerfiles/tomcat/wildbook-start.sh /usr/local/bin/wildbook-start.sh +RUN chmod +x /usr/local/bin/wildbook-start.sh + +# Expose the port on which Tomcat will run +EXPOSE 8080 + +# Use custom startup script +CMD ["/usr/local/bin/wildbook-start.sh"] diff --git a/devops/development/.dockerfiles/tomcat/jdoconfig.properties.template b/devops/development/.dockerfiles/tomcat/jdoconfig.properties.template new file mode 100644 index 0000000000..6ab26dd05f --- /dev/null +++ b/devops/development/.dockerfiles/tomcat/jdoconfig.properties.template @@ -0,0 +1,27 @@ +#DataNucleus parameters for object persistence - Docker Configuration with Environment Variables + +# PostgreSQL connection for Docker environment +datanucleus.ConnectionDriverName=org.postgresql.Driver +datanucleus.ConnectionURL=${WILDBOOK_DB_CONNECTION_URL} + +javax.jdo.PersistenceManagerFactoryClass = org.datanucleus.api.jdo.JDOPersistenceManagerFactory +datanucleus.ConnectionUserName = ${WILDBOOK_DB_USER} +datanucleus.ConnectionPassword = ${WILDBOOK_DB_PASSWORD} +datanucleus.schema.autoCreateAll = true +datanucleus.NontransactionalRead = true +datanucleus.Multithreaded = true +datanucleus.RestoreValues = true +datanucleus.storeManagerType = rdbms +datanucleus.maxFetchDepth = -1 +datanucleus.cache.collections.lazy = false + +#connection pooling +datanucleus.connectionPoolingType = dbcp2 + +# DBCP2 Pooling of Connections +datanucleus.connectionPool.maxIdle=10 +datanucleus.connectionPool.minIdle=5 +datanucleus.connectionPool.maxActive=30 +datanucleus.connectionPool.maxWait=-1 +datanucleus.connectionPool.testSQL=SELECT 1 +datanucleus.connectionPool.timeBetweenEvictionRunsMillis=240000 \ No newline at end of file diff --git a/devops/development/.dockerfiles/tomcat/wildbook-start.sh b/devops/development/.dockerfiles/tomcat/wildbook-start.sh new file mode 100644 index 0000000000..2e56cac4b6 --- /dev/null +++ b/devops/development/.dockerfiles/tomcat/wildbook-start.sh @@ -0,0 +1,37 @@ +#!/bin/bash +# Set defaults for database configuration +export WILDBOOK_DB_CONNECTION_URL=${WILDBOOK_DB_CONNECTION_URL:-"jdbc:postgresql://db:5432/wildbook"} +export WILDBOOK_DB_USER=${WILDBOOK_DB_USER:-"wildbook"} +export WILDBOOK_DB_PASSWORD=${WILDBOOK_DB_PASSWORD:-"development"} + +# Seed config files from staging into mounted wildbook_data_dir on first boot +DATA_DIR=/usr/local/tomcat/webapps/wildbook_data_dir +SEED_DIR=/opt/wildbook_seed + +if [ ! -f "$DATA_DIR/WEB-INF/classes/bundles/commonConfiguration.properties" ]; then + echo "Seeding configuration into $DATA_DIR..." + mkdir -p "$DATA_DIR/WEB-INF/classes/bundles" + cp -a "$SEED_DIR/." "$DATA_DIR/" +fi + +# Create symlink for legacy path compatibility +mkdir -p /data +ln -sf "$DATA_DIR" /data/wildbook_data_dir +mkdir -p "$DATA_DIR/WEB-IN" + +# Create required runtime directories on persisted volume +mkdir -p "$DATA_DIR/encounters" +mkdir -p "$DATA_DIR/users" +mkdir -p "$DATA_DIR/upload" + +# Substitute environment variables in jdoconfig.properties +envsubst < "$DATA_DIR/WEB-INF/classes/bundles/jdoconfig.properties.template" > "$DATA_DIR/WEB-INF/classes/bundles/jdoconfig.properties" + +# Fix containerName for WBIA communication +sed -i 's/^containerName=.*/containerName=wildbook/' "$DATA_DIR/WEB-INF/classes/bundles/commonConfiguration.properties" + +# Override SMTP host for MailHog +sed -i 's/^mailHost=.*/mailHost=mailhog/' "$DATA_DIR/WEB-INF/classes/bundles/commonConfiguration.properties" + +# Start Tomcat +exec catalina.sh run diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000000..8ab9ffbf26 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,144 @@ +services: + db: + image: postgres:13.4 + healthcheck: + test: [ "CMD-SHELL", "pg_isready -U postgres || exit 1" ] + interval: 10s + timeout: 5s + retries: 60 + labels: + - autoheal=true + user: postgres + volumes: + - db-pgdata-var:/var/lib/postgresql/data + # DB initialization scripts + - ./devops/development/.dockerfiles/db/initdb.d/:/docker-entrypoint-initdb.d/ + - ./devops/development/.dockerfiles/db/postgresql.conf:/etc/postgresql/postgresql.conf + networks: + - intranet + ports: + # development exposure, not exposed in production + - 5433:5432 + command: -c config_file=/etc/postgresql/postgresql.conf + env_file: .env + environment: + POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}" + WBIA_DB_NAME: "${WBIA_DB_NAME}" + WBIA_DB_USER: "${WBIA_DB_USER}" + WBIA_DB_PASSWORD: "${WBIA_DB_PASSWORD}" + WILDBOOK_DB_NAME: "${WILDBOOK_DB_NAME}" + WILDBOOK_DB_USER: "${WILDBOOK_DB_USER}" + WILDBOOK_DB_PASSWORD: "${WILDBOOK_DB_PASSWORD}" + + wildbook: + build: . + depends_on: + db: + condition: service_healthy + labels: + - autoheal=true + volumes: + # Persist uploaded images and data on host filesystem + - "./wildbook-data:/usr/local/tomcat/webapps/wildbook_data_dir" + - "./logs/:/usr/local/tomcat/logs/" + networks: + - intranet + ports: + - "8080:8080" + env_file: .env + environment: + SITE_NAME: "${SITE_NAME:-wildbook}" + PUBLIC_URL: "${PUBLIC_URL:-/react/}" + # Admin user created on startup, + # https://github.com/WildMeOrg/Wildbook/commit/6d65e70e43691f1b281bb76edf151e5c7cdb7403 + # JAVA_OPTS from old-world wildbook, which gives us 4G heap memory + JAVA_OPTS: "-Djava.awt.headless=true -Xms4096m -Xmx4096m" + + opensearch: + image: opensearchproject/opensearch:2.15.0 + healthcheck: + test: [ "CMD-SHELL", "curl --silent --fail 127.0.0.1:9200/_cluster/health || exit 1" ] + interval: 10s + timeout: 5s + retries: 60 + labels: + - autoheal=true + volumes: + - opensearch-var1:/usr/share/opensearch/data + ulimits: + memlock: + soft: -1 + hard: -1 + networks: + - intranet + ports: + # development exposure, not exposed in production + - 9200:9200 + - 9300:9300 + env_file: .env + environment: + - plugins.security.disabled=true + - node.name=opensearch + #- discovery.seed_hosts=elasticsearch2,elasticsearch3 + #- cluster.initial_master_nodes=elasticsearch,elasticsearch2,elasticsearch3 + #- discovery.seed_hosts=opensearch2 + - cluster.initial_master_nodes=opensearch + - bootstrap.memory_lock=true + - cluster.routing.allocation.disk.threshold_enabled=${ES_THRESHOLD:-true} + - "ES_JAVA_OPTS=-Xms512m -Xmx512m" + - "OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD}" + + # MailHog for development email testing + mailhog: + image: mailhog/mailhog:latest + networks: + - intranet + ports: + - "1025:1025" # SMTP port + - "8025:8025" # Web UI port + + wbia: + # https://github.com/WildMeOrg/wildbook-ia + image: wildme/wbia:nightly + command: ["--db-uri", "${WBIA_DB_URI}"] + depends_on: + db: + condition: service_healthy + # healthcheck: # WBIA defines it's own health check and is already labeled for autoheal + # labels: + # - autoheal=true + volumes: + - wbia-database-var:/data/db + - wbia-cache-var:/cache + networks: + - intranet + ports: + - "82:5000" + env_file: .env + environment: + WBIA_DB_URI: "${WBIA_DB_URI}" + HOUSTON_CLIENT_ID: "${HOUSTON_CLIENT_ID}" + HOUSTON_CLIENT_SECRET: "${HOUSTON_CLIENT_SECRET}" + + autoheal: + image: willfarrell/autoheal + volumes: + - /var/run/docker.sock:/var/run/docker.sock + environment: + AUTOHEAL_CONTAINER_LABEL: "autoheal" + AUTOHEAL_INTERVAL: 15 + AUTOHEAL_START_PERIOD: 600 + AUTOHEAL_DEFAULT_STOP_TIMEOUT: 60 + restart: always + +networks: + intranet: + +volumes: + db-pgdata-var: + wildbook-var: + wildbook-data: + opensearch-var1: + opensearch-var2: + wbia-database-var: + wbia-cache-var: diff --git a/frontend/maven-build.sh b/frontend/maven-build.sh index fd7b88d575..2162d524a0 100755 --- a/frontend/maven-build.sh +++ b/frontend/maven-build.sh @@ -1,5 +1,11 @@ #!/bin/sh +# Skip frontend build if running in Docker (Docker builds it separately) +if [ "$SKIP_FRONTEND_BUILD" = "true" ]; then + echo "Skipping frontend build (SKIP_FRONTEND_BUILD=true)" + exit 0 +fi + # it seems like we dont need a full/absolute url here #export PUBLIC_URL=https://example.com/react/ export PUBLIC_URL=/react/ @@ -9,7 +15,7 @@ npm install react-app-rewired cd frontend -# Use `npm ci` for consistent and faster installs in production, as it installs exact versions +# Use `npm ci` for consistent and faster installs in production, as it installs exact versions # from `package-lock.json` without modifying it, ensuring stability across environments. npm ci @@ -19,9 +25,6 @@ npm run build rsync -a build/ ../src/main/webapp/react - - # hacky cleanup of changes left over cd .. git checkout -- package.json package-lock.json - From fe60fb5413bee3c7445077747ecb08a498400f98 Mon Sep 17 00:00:00 2001 From: James-Burgess Date: Tue, 2 Jun 2026 10:21:37 +0000 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=93=96=20Update=20readme=20with=20new?= =?UTF-8?q?=20running=20instructions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 120 ++++++++++++++++++------------------------- docs/Contributing.md | 66 ++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 70 deletions(-) create mode 100644 docs/Contributing.md diff --git a/README.md b/README.md index 07aa775577..5d90569ef1 100755 --- a/README.md +++ b/README.md @@ -9,75 +9,54 @@ Wildbook is an open source software framework to support mark-recapture, molecul - provides a platform for animal biometrics that supports easy data access and facilitates matching application deployment for multiple species ## Getting Started with Wildbook -Wildbook is a long-standing tool that support a wide variety of researchers and species. The Wild Me team is working on revamping the tool as a true open source project, so if you have ideas and are excited to help, reach out to us on the [Wild Me Development Discord](https://discord.gg/zw4tr3RE4R)! -## Pull Request Workflow -All contributions should be made from a fork off of the Wildbook repo. While there are a number of repositories for specific Wildbook communities, large scale development is driven from the main repository. +Wildbook is a long-standing tool that support a wide variety of researchers and species. +The Wild Me team is working on revamping the tool as a true open source project, so if you have ideas and are excited to help, reach out to us on the [Wild Me Development Discord](https://discord.gg/zw4tr3RE4R)! -### Fork Wildbook -To start, you will need to be signed in to your GitHub account, have admin access to your OS's terminal, and have Git installed. -1. From your browser, in the top right corner of the [Wildbook repo](https://github.com/WildMeOrg/Wildbook), click the **Fork** button. Confirm to be redirected to your own fork (check the url for your USERNAME in the namespace). -1. In your terminal, enter the command `git clone https://github.com/USERNAME/Wildbook` -1. Once the Wildbook directory becomes available in your working directory, move to it with the command `cd Wildbook` -1. Add a reference to the original repo, denoting it as the upstream repo. +### Quick Start with Docker + +The easiest way to run Wildbook locally is with Docker Compose. This builds the full application (including the frontend) and starts all required services. + +**Prerequisites:** Docker and Docker Compose installed on your system. + +```bash +# 1. Create your .env file from the repo root's .env defaults +# (defaults already provided no changes needed for local dev) + +cp devops/development/_env.template .env + +# 2. Start all services + +docker compose up -d ``` -git remote add upstream https://github.com/WildMeOrg/Wildbook -git fetch upstream + +The first build will take a few minutes as it compiles the Java project and builds the React frontend. Subsequent starts are faster. + +**What's running:** + +| Service | Description | Port | +| ------------ | -------------------------------- | ---------------------- | +| `wildbook` | Tomcat with Wildbook application | `8080` | +| `db` | PostgreSQL database | `5433` | +| `opensearch` | Search index | `9200` | +| `mailhog` | Email capture for dev | SMTP `1025`, UI `8025` | +| `wbia` | Image analysis (Wildbook IA) | `82` | + +Once started, open **http://localhost:8080** in your browser. Default login: `tomcat` / `tomcat123`. + +Outbound emails are captured by MailHog. View them at **http://localhost:8025**. + +**Note:** OpenSearch requires a higher `vm.max_map_count` on Linux. Run once: + +```bash +sudo sysctl -w vm.max_map_count=262144 ``` +### Legacy development +For legacy docker build and instructions on locally building the .war file see [`devops/README.md`](devops/README.md) for detailed instructions. -### Create Local Branch -You will want to work in a branch when doing any feature development you want to provide to the original project. -1. Verify you are on the main branch. The branch you have checked out will be used as the base for your new branch, so you typically want to start from main. -`git checkout main` -1. Create your feature branch. It can be helpful to include the issue number (ISSUENUMBER) you are working to address. -`git branch ISSUENUMBER-FEATUREBRANCHNAME` -1. Change to your feature branch so your changes are grouped together. -`git checkout ISSUENUMBER-FEATUREBRANCHNAME` -1. Update your branch (this is not needed if you just created new branch, but is a good habit to get into). -` git pull upstream main` - -### Set Up Development Environment with Docker -For easiest development, you will need to set up your development environment to work with Docker. See [`devops/README.md`](devops/README.md) for detailed instructions. - -### Making Local Changes -Make the code changes necessary for the issue you're working on. You will need to either redeploy your war file (see [`devops/README.md`](devops/README.md)) or redeploy your front end directly (see [`frontend.README.md`](frontend/README.md)) for testing locally. - -The following git commands may prove useful. -* `git log`: lastest commits of current branch -* `git status`: current staged and unstaged modifications -* `git diff --staged`: the differences between the staging area and the last commit -* `git add : add files that have changes to staging in preparation for commit -* `git commit`: commits the stagged files, opens a text editor for you to write a commit log - -### Unit Tests -We are working on building up test coverage. Current requirements are: -* Do not drop the percentage of test coverage (exceptions will be made for large scale changes on case-by-case basis) -* Do not break existing tests - -See [test coverage guidelines](src/test/README.md) for how to develop your tests. - -### Submit PR -Up to this point, all changes have been done to your local copy of Wildbook. You need to push the new commits to a remote branch to start the PR process. - -1. Now's the time clean up your PR if you choose to squash commits, but this is not required. If you're looking for more information on these practices, see this [pull request tutorial](https://yangsu.github.io/pull-request-tutorial/). -1. Push to the remote version of your branch ` git push ` -`git push origin ISSUENUMBER-FEATUREBRANCHNAME` -1. When prompted, provide your username and GitHub Personal Access Token. If you do not have a GitHub Personal Access Token, or do not have one with the correct permissions for your newly forked repository, you will need to [create a Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). -1. Check the fork's page on GitHub to verify that you see a new branch with your added commits. You should see a line saying "This branch is X commits ahead" and a **Pull request** link. -1. Click the **Pull request** link to open a form that says "Able to merge". (If it says there are merge conflicts, go the for help). -1. Use an explicit title for the PR and provide details in the comment area. Details can include text, or images, and should provide details as to what was done and why design decisions were made. -1. Click **Create a pull request**. - -### Respond to feedback -At this point, it's on us to get you feedback on your submission! Someone from the Wild Me team will review the project and provide any feedback that may be necessary. If changes are recommended, you'll need to checkout the branch you were working from, update the branch, and make these changes locally. - -1. `git checkout ISSUENUMBER-FEATUREBRANCHNAME` -1. `git pull upstream main` -1. Make required changes -1. `git add ` for all files impacted by changes -1. Determine which method would be most appropriate for updating your PR - * `git commit --ammend` if the changes are small stylistic changes - * `git commit` if the changes involved significant rework and require additional details +### Frontend-Only Development + +If you are only making changes to the React frontend, see [`frontend/README.md`](frontend/README.md) for a faster rebuild cycle. ## Machine Learning in Wildbook @@ -90,14 +69,15 @@ Wild Me (wildme.org) engineering staff provide support for Wildbook. You can con We provide support during regular office hours on Mondays and Tuesdays. ## Support resources -* User documentation is available at [Wild Me Documentation](http://wildbook.docs.wildme.org) -* For user support, visit the [Wild Me Community Forum](https://community.wildme.org) -* For contribution guidelines, visit [Wildbook Code Contribution Guidelines](https://wildbook.docs.wildme.org/contribute/code-guide.html) -* For developer support, visit the [Wild Me Development Discord](https://discord.gg/zw4tr3RE4R) -* Email the team at opensource@wildme.org + +- User documentation is available at [Wild Me Documentation](http://wildbook.docs.wildme.org) +- For user support, visit the [Wild Me Community Forum](https://community.wildme.org) +- For contribution guidelines, visit [Wildbook Code Contribution Guidelines](https://wildbook.docs.wildme.org/contribute/code-guide.html) +- For developer support, visit the [Wild Me Development Discord](https://discord.gg/zw4tr3RE4R) +- Email the team at opensource@wildme.org ## History -Wildbook started as a collaborative software platform for globally-coordinated whale shark (Rhincodon typus ) research as deployed in the Wildbook for Whale Sharks (now part of http://www.sharkbook.ai). After many requests to use our software outside of whale shark research, it is now an open source, community-maintained standard for mark-recapture studies. +Wildbook started as a collaborative software platform for globally-coordinated whale shark (Rhincodon typus ) research as deployed in the Wildbook for Whale Sharks (now part of http://www.sharkbook.ai). After many requests to use our software outside of whale shark research, it is now an open source, community-maintained standard for mark-recapture studies. Wildbook is a trademark of [Conservation X Labs](https://conservationxlabs.com/), a 501(c)(3) non-profit organization, and is supported by the [Wild Me](https://wildme.org) team. diff --git a/docs/Contributing.md b/docs/Contributing.md new file mode 100644 index 0000000000..02ccd4e23d --- /dev/null +++ b/docs/Contributing.md @@ -0,0 +1,66 @@ +## Pull Request Workflow +All contributions should be made from a fork off of the Wildbook repo. While there are a number of repositories for specific Wildbook communities, large scale development is driven from the main repository. + +### Fork Wildbook +To start, you will need to be signed in to your GitHub account, have admin access to your OS's terminal, and have Git installed. +1. From your browser, in the top right corner of the [Wildbook repo](https://github.com/WildMeOrg/Wildbook), click the **Fork** button. Confirm to be redirected to your own fork (check the url for your USERNAME in the namespace). +1. In your terminal, enter the command `git clone https://github.com/USERNAME/Wildbook` +1. Once the Wildbook directory becomes available in your working directory, move to it with the command `cd Wildbook` +1. Add a reference to the original repo, denoting it as the upstream repo. +``` +git remote add upstream https://github.com/WildMeOrg/Wildbook +git fetch upstream +``` + +### Create Local Branch +You will want to work in a branch when doing any feature development you want to provide to the original project. +1. Verify you are on the main branch. The branch you have checked out will be used as the base for your new branch, so you typically want to start from main. +`git checkout main` +1. Create your feature branch. It can be helpful to include the issue number (ISSUENUMBER) you are working to address. +`git branch ISSUENUMBER-FEATUREBRANCHNAME` +1. Change to your feature branch so your changes are grouped together. +`git checkout ISSUENUMBER-FEATUREBRANCHNAME` +1. Update your branch (this is not needed if you just created new branch, but is a good habit to get into). +` git pull upstream main` + +### Making Local Changes +Make the code changes necessary for the issue you're working on. You will need to either redeploy your war file (see [`devops/README.md`](devops/README.md)) or redeploy your front end directly (see [`frontend.README.md`](frontend/README.md)) for testing locally. + +The following git commands may prove useful. +* `git log`: lastest commits of current branch +* `git status`: current staged and unstaged modifications +* `git diff --staged`: the differences between the staging area and the last commit +* `git add : add files that have changes to staging in preparation for commit +* `git commit`: commits the stagged files, opens a text editor for you to write a commit log + +### Unit Tests +We are working on building up test coverage. Current requirements are: +* Do not drop the percentage of test coverage (exceptions will be made for large scale changes on case-by-case basis) +* Do not break existing tests + +See [test coverage guidelines](src/test/README.md) for how to develop your tests. + +### Submit PR +Up to this point, all changes have been done to your local copy of Wildbook. You need to push the new commits to a remote branch to start the PR process. + +1. Now's the time clean up your PR if you choose to squash commits, but this is not required. If you're looking for more information on these practices, see this [pull request tutorial](https://yangsu.github.io/pull-request-tutorial/). +1. Push to the remote version of your branch ` git push ` +`git push origin ISSUENUMBER-FEATUREBRANCHNAME` +1. When prompted, provide your username and GitHub Personal Access Token. If you do not have a GitHub Personal Access Token, or do not have one with the correct permissions for your newly forked repository, you will need to [create a Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). +1. Check the fork's page on GitHub to verify that you see a new branch with your added commits. You should see a line saying "This branch is X commits ahead" and a **Pull request** link. +1. Click the **Pull request** link to open a form that says "Able to merge". (If it says there are merge conflicts, go the for help). +1. Use an explicit title for the PR and provide details in the comment area. Details can include text, or images, and should provide details as to what was done and why design decisions were made. +1. Click **Create a pull request**. + +### Respond to feedback +At this point, it's on us to get you feedback on your submission! Someone from the Wild Me team will review the project and provide any feedback that may be necessary. If changes are recommended, you'll need to checkout the branch you were working from, update the branch, and make these changes locally. + +1. `git checkout ISSUENUMBER-FEATUREBRANCHNAME` +1. `git pull upstream main` +1. Make required changes +1. `git add ` for all files impacted by changes +1. Determine which method would be most appropriate for updating your PR + * `git commit --ammend` if the changes are small stylistic changes + * `git commit` if the changes involved significant rework and require additional details + + From 22fc8bce735280027a660cd0b15af1862aa51575 Mon Sep 17 00:00:00 2001 From: James-Burgess Date: Wed, 3 Jun 2026 15:50:24 +0000 Subject: [PATCH 3/6] remove wbia from devlopment compose and skip imagemagik in build stage --- Dockerfile | 2 +- docker-compose.yml | 47 +--------------------------------------------- 2 files changed, 2 insertions(+), 47 deletions(-) diff --git a/Dockerfile b/Dockerfile index 3ae99db384..b9c62a890d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,7 +6,7 @@ FROM maven:3.9.6-eclipse-temurin-21 AS build RUN apt-get update && \ apt-get install -y build-essential curl gnupg && \ curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && \ - apt-get install -y nodejs imagemagick rsync && \ + apt-get install -y nodejs rsync && \ apt-get clean && rm -rf /var/lib/apt/lists/* # Set working directory to the application root diff --git a/docker-compose.yml b/docker-compose.yml index 8ab9ffbf26..4e86e0963c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,8 +6,6 @@ services: interval: 10s timeout: 5s retries: 60 - labels: - - autoheal=true user: postgres volumes: - db-pgdata-var:/var/lib/postgresql/data @@ -17,7 +15,6 @@ services: networks: - intranet ports: - # development exposure, not exposed in production - 5433:5432 command: -c config_file=/etc/postgresql/postgresql.conf env_file: .env @@ -35,8 +32,6 @@ services: depends_on: db: condition: service_healthy - labels: - - autoheal=true volumes: # Persist uploaded images and data on host filesystem - "./wildbook-data:/usr/local/tomcat/webapps/wildbook_data_dir" @@ -61,8 +56,6 @@ services: interval: 10s timeout: 5s retries: 60 - labels: - - autoheal=true volumes: - opensearch-var1:/usr/share/opensearch/data ulimits: @@ -72,16 +65,12 @@ services: networks: - intranet ports: - # development exposure, not exposed in production - 9200:9200 - 9300:9300 env_file: .env environment: - plugins.security.disabled=true - node.name=opensearch - #- discovery.seed_hosts=elasticsearch2,elasticsearch3 - #- cluster.initial_master_nodes=elasticsearch,elasticsearch2,elasticsearch3 - #- discovery.seed_hosts=opensearch2 - cluster.initial_master_nodes=opensearch - bootstrap.memory_lock=true - cluster.routing.allocation.disk.threshold_enabled=${ES_THRESHOLD:-true} @@ -97,41 +86,7 @@ services: - "1025:1025" # SMTP port - "8025:8025" # Web UI port - wbia: - # https://github.com/WildMeOrg/wildbook-ia - image: wildme/wbia:nightly - command: ["--db-uri", "${WBIA_DB_URI}"] - depends_on: - db: - condition: service_healthy - # healthcheck: # WBIA defines it's own health check and is already labeled for autoheal - # labels: - # - autoheal=true - volumes: - - wbia-database-var:/data/db - - wbia-cache-var:/cache - networks: - - intranet - ports: - - "82:5000" - env_file: .env - environment: - WBIA_DB_URI: "${WBIA_DB_URI}" - HOUSTON_CLIENT_ID: "${HOUSTON_CLIENT_ID}" - HOUSTON_CLIENT_SECRET: "${HOUSTON_CLIENT_SECRET}" - - autoheal: - image: willfarrell/autoheal - volumes: - - /var/run/docker.sock:/var/run/docker.sock - environment: - AUTOHEAL_CONTAINER_LABEL: "autoheal" - AUTOHEAL_INTERVAL: 15 - AUTOHEAL_START_PERIOD: 600 - AUTOHEAL_DEFAULT_STOP_TIMEOUT: 60 - restart: always - -networks: + networks: intranet: volumes: From 58f8f288d6423ad5b2cfa80ff968598e8c803749 Mon Sep 17 00:00:00 2001 From: James-Burgess Date: Thu, 4 Jun 2026 07:17:24 +0000 Subject: [PATCH 4/6] fix bad spacing --- docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker-compose.yml b/docker-compose.yml index 4e86e0963c..158ffafe00 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -86,7 +86,7 @@ services: - "1025:1025" # SMTP port - "8025:8025" # Web UI port - networks: +networks: intranet: volumes: From e50605030ff697f3506699288163877e3a9cd2f3 Mon Sep 17 00:00:00 2001 From: James-Burgess Date: Thu, 4 Jun 2026 12:21:47 +0000 Subject: [PATCH 5/6] correct config for root war file --- devops/development/.dockerfiles/tomcat/server.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devops/development/.dockerfiles/tomcat/server.xml b/devops/development/.dockerfiles/tomcat/server.xml index 66032102d7..8aeb15e38a 100644 --- a/devops/development/.dockerfiles/tomcat/server.xml +++ b/devops/development/.dockerfiles/tomcat/server.xml @@ -161,7 +161,7 @@ - + From d6c8122b0cb3871384286faea801fc7892bbc2a7 Mon Sep 17 00:00:00 2001 From: James-Burgess Date: Thu, 4 Jun 2026 12:24:03 +0000 Subject: [PATCH 6/6] set base url to be 8080 to match the server config and make image loading work --- devops/development/_env.template | 1 + 1 file changed, 1 insertion(+) diff --git a/devops/development/_env.template b/devops/development/_env.template index 32faac4a13..08a4260f01 100644 --- a/devops/development/_env.template +++ b/devops/development/_env.template @@ -4,6 +4,7 @@ # - $WILDBOOK_BASE_DIR/logs/ (logs will go here) WILDBOOK_BASE_DIR=~/wildbook-dev +SERVER_URL=http://localhost:80 # for smtp (postfix) usage: