diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000000..b16f8e5a010 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,4 @@ +# These are supported funding model platforms + +github: [osgeo] +cusotm: ['https://github.com/geonetwork/core-geonetwork/wiki#financial-support','https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=LDTWEL3XKUVU8&source=url','https://www.osgeo.org/about/how-to-become-a-sponsor/'] diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000000..79c4ed02a0c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ + + + + + +# Checklist + +- [ ] I have read the [contribution guidelines](https://github.com/geonetwork/core-geonetwork/blob/main/CONTRIBUTING.md +- [ ] *Pull request* provided for `main` branch, backports managed with label +- [ ] *Good housekeeping* of code, cleaning up comments, tests, and documentation +- [ ] *Clean commit history* broken into understandable chucks, avoiding big commits with hundreds of files, cautious of reformatting and whitespace changes +- [ ] *Clean commit message*s, longer verbose messages are encouraged +- [ ] *API Changes* are identified in commit messages +- [ ] *Testing* provided for features or enhancements using [automatic tests](https://github.com/geonetwork/core-geonetwork/blob/main/software_development/TESTING.md)) +- [ ] *User documentation* provided for new features or enhancements in [mannual](https://github.com/geonetwork/core-geonetwork/tree/main/docs/manual) +- [ ] *Build documentation* provided for development instructions in `README.md` files +- [ ] *Library management* using `pom.xml` dependency management. Update build documentation with intended library use and library tutorials or documentation + + diff --git a/.gitignore b/.gitignore index 3939710dfe7..10051ab54fc 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ git*.properties */*/target/ */target/ .*/ +!.github #GeoNetwork* /geonetwork* camel-harvesters/wfsfeature-harvester/logs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab418f3efe0..e8065add3b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,6 @@ Thank you for contributing to GeoNetwork: * Build documentation: All build and development instructions managed in repository `README.md` files. -* New libraries: Do not commit jars, use maven `pom.xml` to declare dependencies where needed, and `src/pom.xml` dependency management to manage version numbers. Document what the library does in GeoNetwork, how it interacts or extends GeoNetwork, with references to official library tutorials or documentation. +* New libraries: Do not commit jars, use maven `pom.xml` to declare dependencies where needed, and `src/pom.xml` dependency management to manage version numbers. Use build documentation to share what the library does in GeoNetwork, how it interacts or extends GeoNetwork, with references to official library tutorials or documentation. For more information see [How to contribute](https://github.com/geonetwork/core-geonetwork/wiki/How-to-contribute) (wiki). diff --git a/README.md b/README.md index 6e2d522512e..d33680cf452 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # GeoNetwork Open-source -# Build Health +## Build Health [![Build Status](https://github.com/geonetwork/core-geonetwork/actions/workflows/linux.yml/badge.svg?branch=main)](https://github.com/geonetwork/core-geonetwork/actions/workflows/linux.yml?query=branch%3Amain) -# Features +## Features * Immediate search access to local and distributed geospatial catalogues * Uploading and downloading of data, graphics, documents, pdf files and any other content type @@ -15,15 +15,18 @@ * Fine-grained access control with group and user management * Multi-lingual user interface -# Documentation +## Documentation -User documentation is managed in the [geonetwork/doc](https://github.com/geonetwork/doc) repository covering all releases of GeoNetwork. +The Geonetwork Manual and Online Help are included in the `docs/manual` folder. This content is compiled into html pages during a release for a publishing on docs.geonetwork-opensource.org website. -The `docs` folder includes [geonetwork/doc](https://github.com/geonetwork/doc) as a git submodule. This documentation is compiled into html pages during a release for publishing on the [geonetwork-opensource.org](http://geonetwork-opensource.org) website. +* [docs.geonetwork-opensource.org](https://docs.geonetwork-opensource.org) -Developer documentation located in README.md files in the code-base: +The online help is compiled into html pages during a release and is included in the `war` web archive. -* General documentation for the project as a whole is in this README.md -* [Software Development Documentation](/software_development/) provides instructions for setting up a development environment, building Geonetwork, compiling user documentation, and making a releases -* Module specific documentation can be found in each module (assuming there is module specific documentation required) +## Developer Documentation +Developer documentation located in ``README.md`` files in the code-base: + +* General documentation for the project as a whole is in this [README.md](README.md) +* [Software Development Documentation](/software_development/) provides instructions for setting up a development environment, building Geonetwork, compiling user documentation, and making a releases. +* Module specific documentation can be found in each module: diff --git a/datastorages/README.md b/datastorages/README.md new file mode 100644 index 00000000000..721c1687d55 --- /dev/null +++ b/datastorages/README.md @@ -0,0 +1,12 @@ +# Data storage + +Extensions for data storage (used for storage resources such as record attachments and thumbnails). + +Core provides the default implementation for a data directory: + +* org.fao.geonet.resource.FileResources + +For more information see: + +* org.fao.geonet.resource.Resources + diff --git a/datastorages/cmis/README.md b/datastorages/cmis/README.md new file mode 100644 index 00000000000..5bd20e924f1 --- /dev/null +++ b/datastorages/cmis/README.md @@ -0,0 +1,11 @@ +# CMIS Data storage + +Extension for data storage (used for storage resources such as record attachments and thumbnails). + +* cmis: content management interoperability services + +This data storage is based on the Apache Chemistry project which has been retired. + +Reference: + +* https://chemistry.apache.org/java/opencmis.html diff --git a/datastorages/jcloud/README.md b/datastorages/jcloud/README.md new file mode 100644 index 00000000000..43723d5659c --- /dev/null +++ b/datastorages/jcloud/README.md @@ -0,0 +1,10 @@ +# JCloud Data storage + +Extension for data storage (used for storage resources such as record attachments and thumbnails). + +This extension uses the Apache JCloud library for portable storage across different cloud providers. + +Reference: + +* https://jclouds.apache.org + diff --git a/datastorages/s3/README.md b/datastorages/s3/README.md new file mode 100644 index 00000000000..10cbc40199e --- /dev/null +++ b/datastorages/s3/README.md @@ -0,0 +1,9 @@ +# S3 Data storage + +Extension for data storage (used for storage resources such as record attachments and thumbnails). + +This extension uses Amazon Web Services Simple Storage Service (S3) data storage directly. + +Reference: + +* https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html diff --git a/docs/manual/docs/install-guide/installing-from-source-code.md b/docs/manual/docs/install-guide/installing-from-source-code.md index 3bc7237a4e0..00b40f8bbde 100644 --- a/docs/manual/docs/install-guide/installing-from-source-code.md +++ b/docs/manual/docs/install-guide/installing-from-source-code.md @@ -20,8 +20,8 @@ If you need a more powerful container, we recommend [Apache Tomcat](http://tomca We recommend the following stable releases of Tomcat: -- Apache Tomcat 8.5 - Apache Tomcat 9.0 +- Apache Tomcat 8.5 ### Database @@ -159,7 +159,7 @@ Please refer to the [Maven documentation](http://www.sonatype.com/books/mvnref-b ### Run embedded Jetty server -Maven comes with built-in support for Jetty via a [plug-in](http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin). +Maven comes with built-in support for Jetty via a [plug-in](https://eclipse.dev/jetty/documentation/jetty-9/index.html#maven-and-jetty). To run GeoNetwork with the embedded Jetty server you have to change directory to the root of the **web** module, and then execute the following Maven command: @@ -167,10 +167,10 @@ To run GeoNetwork with the embedded Jetty server you have to change directory to mvn jetty:run -Penv-dev ``` -After a while, GeoNetwork should be accessible at: +After some moments of startup and initialization, GeoNetwork is available at: -For changes related to the user interface in the ``web-ui`` module or the metadata schemas in the `as` module, these can be deployed in Jetty executing the following Maven command in the **web** module: +For changes related to the user interface in the ``web-ui`` module or the metadata schemas in the `schemeas` module, these can be deployed in Jetty executing the following Maven command in the **web** module: ``` shell -mvn process-resources +mvn process-resources -DschemasCopy=true ``` diff --git a/software_development/BUILDING.md b/software_development/BUILDING.md index d33f68a2122..16fe522d14e 100644 --- a/software_development/BUILDING.md +++ b/software_development/BUILDING.md @@ -1,6 +1,6 @@ # Building -See [Installing from source code](https://geonetwork-opensource.org/manuals/4.0.x/en/install-guide/installing-from-source-code.html) (Installation Guide) +See [Installing from source code](https://docs.geonetwork-opensource.org/latest/install-guide/installing-from-source-code/) (Installation Guide) Build GeoNetwork ---------------- @@ -102,7 +102,6 @@ GeoNetwork requires an Elasticsearch instance as an index. 3. For alternatives see [es/readme](../es/README.md). - Run Kibana ---------- diff --git a/software_development/GITHUB.md b/software_development/GITHUB.md index 870aaf52de6..defd00d6e85 100644 --- a/software_development/GITHUB.md +++ b/software_development/GITHUB.md @@ -33,4 +33,4 @@ To checkout a branch from upstream:: GeoNetwork uses feature branches for development, and a pull-request workflow for review: * [Contributing](../CONTRIBUTING.md). -* [Making a pull request](https://geonetwork-opensource.org/manuals/trunk/en/contributing/making-a-pull-request.html). +* [Making a pull request](https://docs.geonetwork-opensource.org/latest/contributing/making-a-pull-request/). diff --git a/software_development/OVERVIEW.md b/software_development/OVERVIEW.md index 7c4cdd29acc..0e179d1de80 100644 --- a/software_development/OVERVIEW.md +++ b/software_development/OVERVIEW.md @@ -1,4 +1,4 @@ -# GeoNetwork Architecture Overview +# GeoNetwork Overview GeoNetwork is a modular application, managed using the spring framework, divided into clear application tiers. @@ -9,19 +9,73 @@ GeoNetwork uses a wide range of technologies: * [Angular](https://angular.io/) web framwork providing model-view-controller architecture with data model binding * [Apache Lucene](https://lucene.apache.org) text index to facilitate searching * [Bootstrap](https://getbootstrap.com/) front-end open source toolkit providing response page layout -* [Elasticsearch](https://www.elastic.co/elasticsearch/) to manage usage statistics and reporting +* [Elasticsearch](https://www.elastic.co/elasticsearch/) full-text search * [GeoTools](https://geotools.org/) Java GIS toolkit used to provide a spatial index * [OpenLayers](http://openlayers.org) web mapping framework * [Saxon](http://www.saxonica.com/) XSLT engine used extensively to process XML documents * [Spring framework](https://spring.io/) Java web application framework used to "wire" components together -GeoNetwork is Java Web Application, requiring an application server to operate: - -* [Jetty](https://www.eclipse.org/jetty/) application server for standaline distribution -* [Apache Tomcat](http://tomcat.apache.org/) application server for WAR distribution - GeoNetwork configuration is managed via: * Configuration is managed via [Hibernate Object/Relational Mapping](https://hibernate.org/orm/) with [H2 Database Engine](https://www.h2database.com/) default for local testing, [PostgreSQL](https://www.postgresql.org/) recommended for production. Additional dialects are available for environments restricted to Oracle or SQLServer. * Data Directory for the management of thumbnails, attachments and other application files + +## Architecture + +GeoNetwork is a modular web application, managed using the spring framework, divided into clear application tiers. + +![GeoNetwork Architecture](geonetwork-architecture.png "GeoNetwork Architecture") + +The application is built on top of: + +* Elasticsearch: full-text search +* Database: record persistance +* Data directory: attachments and application files + +## Technologies + +## Hibernate Object/Relational Mappping + + + +Geonetwork Reference: + +* [domain](../domain/README.md) + +Reference: + +* https://hibernate.org/orm/ + +### Java Enterprise Edition + +GeoNetwork is a Java "web application", following Java Enterprise Edition standard (establishing Servlet and related interfaces, and the web-application-archive bundle). + +Note: Java Enterprise Edition is in the process of renaming to Jakarata Enterprise Edition + +The ``geonetwork.war`` requires an application server to operate: + +* [Jetty](https://www.eclipse.org/jetty/) application server for standaline distribution. + + Jetty 9 is the last JavaEE compatible release. + +* [Apache Tomcat](http://tomcat.apache.org/) application server for WAR distribution + + Apache Tomcat 9.x is the last JavaEE compatible release. + +Reference: + +* https://javaee.github.io (Legacy Java EE Home) + +## Libraries + +### mapfish-print-v2 + +The mapfish-print-v2 library is used for PDF generation, using a combinatino of GeoTools and OpenPDF library. + +The library is used for thumbnail generation. + +Reference: + +* http://github.com/mapfish/mapfish-print-v2 +* https://github.com/LibrePDF/OpenPDF diff --git a/software_development/README.md b/software_development/README.md index 4d58433a27b..94b0b7de045 100644 --- a/software_development/README.md +++ b/software_development/README.md @@ -1,8 +1,8 @@ # Software Development -This manual is for software developers customizing or developing GeoNetwork: +This manual is for developers customizing or developing GeoNetwork: -* [GeoNetwork Architecture Overview](OVERVIEW.md) describing technologies used and application components. +* [Overview](OVERVIEW.md) describing architecture, technologies, and libraries used. * Development environment: * [Tools](TOOLS.md) @@ -13,15 +13,15 @@ This manual is for software developers customizing or developing GeoNetwork: * [Eclipse IDE](ECLIPSE.md) * [IntelliJ IDE](INTELLIJ.md). - See [Installing from source code](https://geonetwork-opensource.org/manuals/4.0.x/en/install-guide/installing-from-source-code.html) (Installation Guide) - -* Writing documentation: see [Writing documentation](https://geonetwork-opensource.org/manuals/trunk/en/contributing/writing-documentation.html) (Contributing Guide). -* Release process: See [Doing a release](https://geonetwork-opensource.org/manuals/trunk/en/contributing/doing-a-release.html) (Contributing Guide). + See [Installing from source code](https://docs.geonetwork-opensource.org/latest/install-guide/installing-from-source-code/) (Installation Guide) +* Writing documentation: see [Documentation Guide](https://docs.geonetwork-opensource.org/latest/devel/docs/) (Contributing Guide). +* Writing documentation: see [Documentation Guide](https://docs.geonetwork-opensource.org/latest/devel/docs/) (Contributing Guide). +* Release process: See [Doing a release](https://docs.geonetwork-opensource.org/latest/contributing/doing-a-release/) (Contributing Guide). If you just want to use the software and are looking for instructions on how to do that, there is a lot of documentation for users, administrators, metadata editors and application -maintainers at: [GeoNetwork Documentation](http://geonetwork-opensource.org/manuals/trunk/eng/users/index.html). +maintainers at: [GeoNetwork Documentation](https://docs.geonetwork-opensource.org/latest/). # Quickstart @@ -48,3 +48,4 @@ Get GeoNetwork running - the short path: ``` 4. The application is opened on http://localhost:8080/geonetwork + diff --git a/software_development/TOOLS.md b/software_development/TOOLS.md index 0f7df84beec..2bd1f556735 100644 --- a/software_development/TOOLS.md +++ b/software_development/TOOLS.md @@ -19,24 +19,77 @@ Our source code is maintained on GitHub: * [iso19115-3.2018](https://github.com/metadata101/iso19115-3.2018) -## Java 8 +## Java 11 -GeoNetwork requires a Java 8 development environment: +GeoNetwork requires a Java 11 development environment: -* Recommend using the Java 8 distribution available from your operating system -* [Adoptium OpenJDK8 (LTS)](https://adoptium.net/temurin/archive/?version=8) for windows or macOS installers +* Recommend using the Java 11 distribution available from your operating system +* [Adoptium OpenJDK8 (LTS)](https://adoptium.net/temurin/archive/?version=11) for windows or macOS installers -We do not support development on Java 11 at this time. +We no longer support Java 8 at this time. + +## Elasticsearch + +GeoNetwork uses Elasticsearch as a full-text search engine. + +``` +cd es +docker-compose up +``` + +* Elasticsearch: http://localhost:9200 +* Kibana: http://localhost:5601 + +GeoNetwork Reference: + +* [es/readme](../es/README.md) + +Reference: + +* https://www.elastic.co/guide/index.html ## Apache Maven We make use of the Apache Maven [Apache Maven](https://maven.apache.org/) build system. +To build and run: +``` +mvn clean install -DskipTests +cd web +mvn jetty:run +``` + +* GeoNetwork: http://localhost:8080/geonetwork + Maven repository is available at repo.osgeo.org: * https://repo.osgeo.org/repository/release/ * https://repo.osgeo.org/repository/snapshot/ -## Sphinx +GeoNetwork Reference + +* [software_development/building](BUIDLING.md) +* [web](../web/README.md) + +Reference: + +* https://maven.apache.org/index.html + +## Material for MkDocs + +Documentation is built using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, built using python ***mkdocs*** generator. + +``` +cd docs/mannual +pip3 install -r requirements.txt +mkdocs serve +``` + +GeoNetwork Reference: + +* [docs/manual](../docs/manual/README.md) + +Reference: -Documentation is built using [Sphinx](https://www.sphinx-doc.org/) python documentation generator. +* https://squidfunk.github.io/mkdocs-material/ +* https://www.mkdocs.org