{"id":21803553,"url":"https://github.com/terrestris/shogun-docker","last_synced_at":"2025-10-29T18:03:25.568Z","repository":{"id":38367974,"uuid":"237183179","full_name":"terrestris/shogun-docker","owner":"terrestris","description":"Docker compose environment for SHOGun","archived":false,"fork":false,"pushed_at":"2025-04-04T06:49:00.000Z","size":146714,"stargazers_count":3,"open_issues_count":6,"forks_count":7,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-05T17:16:07.504Z","etag":null,"topics":["docker","docker-compose","shogun","webgis-framework"],"latest_commit_sha":null,"homepage":"","language":"FreeMarker","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terrestris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-30T09:50:00.000Z","updated_at":"2025-04-04T06:48:52.000Z","dependencies_parsed_at":"2023-02-08T12:16:02.461Z","dependency_job_id":"a936cf55-283c-49ef-a527-14042f86b8d7","html_url":"https://github.com/terrestris/shogun-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fshogun-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fshogun-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fshogun-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrestris%2Fshogun-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terrestris","download_url":"https://codeload.github.com/terrestris/shogun-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766751,"owners_count":21158301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","shogun","webgis-framework"],"created_at":"2024-11-27T11:45:08.731Z","updated_at":"2025-10-29T18:03:25.561Z","avatar_url":"https://github.com/terrestris.png","language":"FreeMarker","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHOGun-Boot Docker\n\nThis project contains a basic docker-compose setup required to develop / run a\n[SHOGun-Boot](https://github.com/terrestris/shogun) webapplication.\n\n## Description 📙\n\nThis repository contains several `docker-compose` configuration files:\n\n- `common-services.yml`: Contains the shared service configurations for all environments.\n- `docker-compose.yml`: Contains the service configurations for DEVELOPMENT.\n- `docker-compose-prod.yml`: Contains the service configurations for PRODUCTION.\n\n## Requirements 🛠️\n\n- docker\n- docker-compose-plugin\n\nPlease note: If you want to develop SHOGun or some of it's components you might need\nadditional tools (e.g. `mvn` and `node`). Consider the README files of the associated\nrepositories for more details.\n\n## System architecture\n\n![System architecture](./docs/components.png)\n\n## Development 🧑‍💻\n\nThis repository contains the required configurations to develop all SHOGun related\ncomponents:\n\n- SHOGun (the backend part)\n- SHOGun-Admin (the UI for handling SHOGun entities)\n- SHOGun-GIS-Client (the default mapping client)\n- SHOGun-GIS-Client example plugin (a dummy example plugin for demonstration purposes)\n\n### Recommended directory structure\n\nTo get things started, please check out all required repositories in the recommended\ndirectory structure:\n\n```bash\nyour-shogun-workspace-directory/\n├── shogun (https://github.com/terrestris/shogun)\n├── shogun-admin (https://github.com/terrestris/shogun-admin)\n├── shogun-gis-client (https://github.com/terrestris/shogun-gis-client)\n├── shogun-gis-client-example-plugin (https://github.com/terrestris/shogun-gis-client-example-plugin)\n└── shogun-docker (this repository)\n```\n\n### Required steps for the very first start\n\n- Check and fulfill all development notes of the child components (e.g. installing the `maven` and `node` dependencies). For the required repositories the following commands should be used:\n  - shogun-gis-client: `npm i`\n  - shogun-gis-client-example-plugin: `npm i`\n  - shogun-admin: `npm i`\n  - shogun: `mvn clean install -DskipTests -Djib.skip=true`\n- Set all required environment variables (and create a local SSL certificate) by executing `./setEnvironment.sh create` (and adjusting the values if needed).\n- If you are using a different directory layout, make sure to adjust the paths in the `.env` file\n- Startup Keycloak via `docker compose up shogun-keycloak shogun-postgis`, import the initial Keycloak data as described in section [Keycloak Import](#import) and shutdown the services again.\n- Execute `chmod -R a+w shogun-solr/solr_data` to allow the solr service to write to the directory.\n\n### Startup\n\nPlease ensure you have checked out all required repositores (see [Recommended directory structure](#recommended-directory-structure))\nand have fulfilled the required steps for the very first start (see [Required steps for the very first start](#required-steps-for-the-very-first-start)).\n\nTo start the services required for development of SHOGun (no custom project), just run:\n\n```bash\ndocker compose up --build\n```\n\nYou can test whether the SHOGun application started by visiting the URL `https://localhost/`.\n\n### Custom project development\n\nThe contents of this repository may be a good starting point for creating a custom project\nbased on [SHOGun](https://github.com/terrestris/shogun).\n\nThere is a SHOGun example app repository at [https://github.com/terrestris/shogun-example-app](https://github.com/terrestris/shogun-example-app) which demonstrates on how SHOGun can be extended for custom implementations and can be used as follows:\n\n1. Create a new folder directory as suggested:\n\n```bash\nyour-custom-shogun-workspace-directory/\n├── shogun-example-app (export of https://github.com/terrestris/shogun-example-app)\n└── shogun-example-docker (export of this repository)\n```\n\n1. Initialize git in both subdirectories (`git init`) and adjust the upstream to your\n   needs (e.g. `git remote add upstream git@github.com:yourorg/shogun-example.git`).\n\n1. (Optional) Make use of the prebuilt images for both the `shogun-admin` and `shogun-gis-client`\n   by adjusting the `docker-compose.yml`:\n\n    ```diff\n    -    build:\n    -      context: ${SHOGUN_ADMIN_DIR}\n    -      dockerfile: Dockerfile.dev\n    -    volumes:\n    -      - ${SHOGUN_ADMIN_DIR}:/app\n    +    image: docker-public.terrestris.de/terrestris/shogun-admin:17.2.0\n    ```\n\n    ```diff\n    -    build:\n    -      context: ${SHOGUN_CLIENT_DIR}\n    -      dockerfile: Dockerfile.dev\n    -    volumes:\n    -      - ${SHOGUN_CLIENT_DIR}:/app\n    +    image: docker-public.terrestris.de/terrestris/shogun-gis-client:10.1.1\n    ```\n\n1. Remove the `shogun-gs-interceptor` service from the `docker-compose.yml`.\n\n1. Update the context path to the `shogun-boot` service:\n\n    ```diff\n    -    context: ${SHOGUN_DIR}/shogun-boot/\n    +    context: ${SHOGUN_DIR}/example-backend/\n    ```\n\n1. Check for all comments _TODO: Adjust to your project_ in the `shogun-example-app` and\n   adjust the appropriate lines to your needs (e.g. the name of the project).\n\n1. Set all required environment variables by executing `./setEnvironment.sh create` (and adjusting the values if needed).\n\n1. Depending on the mode (development or production) of the `shogun-admin` and `shogun-gis-client`,\n   you might need to adjust the reverse proxy settings in the `shogun-nginx/dev/default.conf` file, e.g.:\n\n    ```diff\n    -    proxy_pass http://shogun-admin:8080/;\n    +    proxy_pass http://shogun-admin/;\n    ```\n    ```diff\n    -    proxy_pass http://shogun-client:8080/;\n    +    proxy_pass http://shogun-client/;\n    ```\n\n1. Run the services with `docker compose up` which should be available at `https://localhost/` afterwards.\n\n1. Import the initial Keycloak data, see section [Keycloak Import](#import).\n\n## Test a prebuilt SHOGun 🏭\n\nYou want to see SHOGun in action?\n\n- Set all required environment variables by executing `./setEnvironment.sh create` (and adjusting the values if needed).\n- Import the initial Keycloak data, see section [Keycloak Import](#import).\n\nAnd start the prebuilt images via:\n\n```bash\ndocker compose -f docker-compose-prod.yml up\n```\n\nYou can test whether the SHOGun application started by visiting the URL\n`https://localhost/`.\n\n## Default credentials 🔐\n\n- Keycloak Admin: `admin:shogun`\n- SHOGun Admin: `shogun:shogun`\n- GeoServer: `admin:geoserver`\n\n## PostgreSQL\n\n### Database update\n\nIf you have an existing database from a previous startup and you've updated the PostgreSQL version midway, you might\nencounter an error similar to the following:\n\n```\nFATAL: database files are incompatible with server\nDETAIL: The data directory was initialized by PostgreSQL version 13, which is not compatible with this version 16.1.\n```\n\nIn this case it's necessary to backup and restore all databases manually:\n\n1. Shutdown all running `shogun-docker` containers (if needed).\n2. Rename the existing database directory, e.g. to `postgresql_data_v13` via\n   `mv ./shogun-postgis/postgresql_data/ ./shogun-postgis/postgresql_data_v13`.\n3. Create a `docker-compose-v13.yml` containing:\n\n```yml\nservices:\n  shogun-postgis-old:\n    container_name: shogun-postgis-old\n    # Adjust the db version to your existing one\n    image: postgis/postgis:13-3.4-alpine\n    environment:\n      POSTGRES_USER: ${POSTGRES_USER}\n      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}\n    volumes:\n      # Set the renamed database directory name from above\n      - ./shogun-postgis/postgresql_data_v13:/var/lib/postgresql/data:Z\n```\n\n4. Start the container via `docker compose -f docker-compose-v13.yml up`.\n5. Create dumps of all relevant databases (usually `keycloak` and `shogun`):\n\n```bash\n# Change the user if needed\ndocker exec -it shogun-postgis-old pg_dump -C -h localhost -p 5432 -U shogun -d keycloak \u003e ./shogun-postgis/keycloak.sql\ndocker exec -it shogun-postgis-old pg_dump -C -h localhost -p 5432 -U shogun -d shogun \u003e ./shogun-postgis/shogun.sql\n```\n\n6. Stop the container.\n7. Start the updated/current database container via `docker compose up shogun-postgis` (make sure\n   that `./shogun-postgis/postgresql_data` is empty and the directory `./shogun-postgis/init_data` is **not** mounted).\n8. Import the dumps:\n\n```bash\n# Change the user if needed\ndocker exec -i shogun-postgis psql -h localhost -p 5432 -U shogun \u003c ./shogun-postgis/keycloak.sql\ndocker exec -i shogun-postgis psql -h localhost -p 5432 -U shogun \u003c ./shogun-postgis/shogun.sql\n```\n\n9. Shutdown the database container and restart the full setup with `docker compose up` (remount\n   the `./shogun-postgis/init_data` if needed).\n10. All files/directories created in the steps above (`docker-compose-v13.yml`, `./shogun-postgis/keycloak.sql`,\n    `./shogun-postgis/shogun.sql`, `./shogun-postgis/postgresql_data_v13`) can be removed if needed.\n\n## GeoServer\n\n### Plugins\n\nThe following [official extensions](https://geoserver.org/release/stable/) are installed in GeoServer:\n\n- geofence-server-postgres\n- importer\n- web-resource\n- [sec-keycloak](https://github.com/geoserver/geoserver/tree/main/src/community/security/keycloak)\n\n#### Build the Keycloak extension\n\nIf you need to build the keycloak community extension (e.g. while updating the GeoServer), please proceed as follows:\n\n```bash\n# go to your local GeoServer checkout\ngit pull upstream main --tags\ngit checkout \u003cVERSION\u003e # e.g. git checkout 2.22.2\ncd src/community\nmvn clean install -PcommunityRelease,assembly -DskipTests # this may take a while!\n\n# release archives available at src/comunity/target/release/\n```\n\nAfterwards [download the gson jar](https://mvnrepository.com/artifact/com.google.code.gson/gson/2.8.9) in version 2.8.9 and put it into the extension's zip archive.\n\n### Export GeoFence configuration\n\nTo export the current configuration of GeoFence just execute:\n\n```bash\ndocker exec -it shogun-postgis pg_dump -C -h localhost -p 5432 -U shogun geofence \u003e ./shogun-postgis/init_data/02_init_geofence.sql\n```\n\n## Keycloak\n\n### Export\n\nWhile the Keycloak docker container is running execute:\n\n```bash\ndocker compose exec shogun-keycloak /opt/keycloak/bin/kc.sh export --file /tmp/keycloak_export.json\n```\n\nWait until finished and copy the configuration to your host:\n\n```bash\ndocker compose cp shogun-keycloak:/tmp/keycloak_export.json ./shogun-keycloak/init_data/keycloak_export.json\n```\n\n### Import\n\nCopy the configuration to the running Keycloak container:\n\n```bash\ndocker compose cp ./shogun-keycloak/init_data/keycloak_export.json shogun-keycloak:/tmp/keycloak_export.json\n```\n\nand start the import with:\n\n```bash\ndocker compose exec shogun-keycloak /opt/keycloak/bin/kc.sh import --file /tmp/keycloak_export.json\n```\n\n## Solr\n\nThe solr instance is preconfigured with a core named `search`. This can be used immediately after start to import documents.\n\nTo avoid error on insufficient permissions while accessing solr update folder permissions as follows:\n\n```bash\nsudo addgroup --gid 8983 solr\nsudo chown -R .solr shogun-solr\nsudo chmod -R g+w shogun-solr\n```\n\n## Notes for production\n\nIf you plan to make use of this setup in production, you're highly encouraged to do so.\n\nBut after the initial installation we strongly recommend to change some defaults:\n\n- Regenerate the default Keycloak client secrets for all clients of *confidential access* type (e.g. `shogun-geoserver`):\n  - See the [documentation](https://www.keycloak.org/docs/latest/server_admin/index.html#_client-credentials).\n  - The secret for the `shogun-geoserver` client needs to be adjusted in the `shogun-keycloak` role service\n    afterwards.\n- Change all default passwords:\n  - GeoServer:\n    - Change the password of the `admin` user (see the [documentation](https://docs.geoserver.org/stable/en/user/security/webadmin/ugr.html#security-webadmin-ugr)).\n    - [Update the keystore password](https://docs.geoserver.org/stable/en/user/security/webadmin/passwords.html#security-webadmin-masterpasswordprovider), store it somewhere not accessible by anyone and delete the file `shogun-geoserver/geoserver_data/security/masterpw.info`.\n  - PostgreSQL:\n    - Change the password of the `shogun` user via `docker exec shogun-postgis psql -U shogun -c \"ALTER USER shogun PASSWORD '\u003cnew-password\u003e';\"`.\n    - The password needs to be changed in the `.env` file and in all relevant GeoServer data sources accordingly.\n  - Keycloak:\n    - Change the password of the `admin` user (see the [documentation](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-setting-password-user_server_administration_guide)).\n    - The password needs to be changed in the `.env` file accordingly.\n\n**Note:** Please recheck your installation critically if you need to adjust other parts as well. We don't give any warranty this list is complete!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrestris%2Fshogun-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterrestris%2Fshogun-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrestris%2Fshogun-docker/lists"}