.. _ref_Getting_Started_projects: Getting Started ============================== This section will show you how to create your MapStore standard downstream project and setup the development environment. Note: ensure to install all the needed tools, see documentation for more info https://mapstore2.readthedocs.io/en/latest/developer-guide/developing/ The aim of the section is to have a MapStore project running locally: .. figure:: ../img/default-project-homepage.png :alt: Default homepage of the MapStore project Create Project ----------------- Clone the MapStore2 repository in the local workspace to generate the downstream project and install all the dependencies .. code-block:: sh git clone https://github.com/geosolutions-it/MapStore2 -b # e.g. git clone https://github.com/geosolutions-it/MapStore2 -b 2023.01.xx .. code-block:: sh cd MapStore2 .. code-block:: sh npm install Create the new project by running the following script from the MapStore2 folder .. code-block:: sh node ./createProject.js the command line will prompt some information to create the project that needs to be filled as following (the default value, between parenthesis, will be used if you press enter) .. code-block:: sh Project Type (standard): Project Name: MyMapStoreProject Project Version (1.0.0): Project Description (Project Name): A sample project for the training Repository URL: Output folder: ../MyMapStoreProject This process will create the new project called ``MyMapStoreProject`` in the *Output folder* indicated (``../MyMapStoreProject``). Navigate to the new ``MyMapStoreProject`` folder to see the files created and start working with it. .. code-block:: sh cd ../MyMapStoreProject .. code-block:: sh npm install .. note:: If initially, you have cloned the project from master tag, but you want to **align mapstore to a specific release** like `2023.01.xx `__ , then we suggest to do also the following steps, otherwise the branch used during project creation is maintained in the submodule To change the version of the MapStore2 submodule in the project to match the current stable branch navigate inside the MapStore2 submodule .. code-block:: sh cd ./MapStore2 fetch all the available branches/tags from the origin remote .. code-block:: sh git fetch origin switch to the stable branch .. code-block:: sh git checkout # e.g. git checkout v2023.01.00 after the checkout we can return to the project folder .. code-block:: sh cd .. .. note:: Now you can remove the MapStore2 you cloned, that is not needed anymore. Include print module -------------------------------- The Print plugin will work only if the plugin module is included correctly. Here the steps to add the backend printing module modify the build.sh file to include the -Pprinting profile .. code-block:: diff #!/bin/bash set -e export GITREV=`git log -1 --format="%H"` export VERSION="SNAPSHOT-$GITREV" npm install npm run compile npm run lint if [ $# -eq 0 ] then - mvn clean install -Dmapstore2.version=$VERSION + mvn clean install -Dmapstore2.version=$VERSION -Pprinting else - mvn clean install -Dmapstore2.version=$1 + mvn clean install -Dmapstore2.version=$1 -Pprinting fi create a printing directory and copy all the default configuration and image files .. code-block:: sh mkdir -p backend/resources/printing/ .. code-block:: sh cp -a MapStore2/java/printing/resources/geoserver/print/. backend/resources/printing/ update the copy resource execution inside the ``web/pom.xml`` file to target the new configuration folder instead of the MapStore submodule one .. code-block:: diff printing process-classes copy-resources ${basedir}/target/MyMapStoreProject/printing UTF-8 - ${basedir}/../MapStore2/java/printing/resources/geoserver/print + ${basedir}/../backend/resources/printing * Run development environment locally ----------------------------------- There are two ways of starting the local environment: - with a local embedded backend instance - with an external backend instance local embedded backend instance _______________________________ In order to use the local backend instance together with the frontend part run .. code-block:: sh npm start The dev environment runs at: http://localhost:8081/?debug=true#/ **debug=true** allows to enable debug mode and will enable :ref:`redux dev tools ` to be used from the dev tools (F12) of the browser if you have installed it as extension Alternatively, if you have only to change the port or the URL of MapStore backend, but you don't have to do any more changes to the dev server, you can simply define the environment variable .. code-block:: sh export MAPSTORE_BACKEND_BASE_URL=https://localhost:8082/mapstore npm run fe:start # this command lunches only the front-end The backend environment runs at: http://localhost:8080/mapstore/ .. note:: If you want to run the backend alone, separated from the frontend, you have to run the following command. (it will start a local instance of the compiled ``mapstore.war``) .. code-block:: sh npm run be:start The MapStore application should run at: http://localhost:8080/mapstore For the frontend alone you have to run: .. code-block:: sh npm run fe:start When you are done with your development you may want to test them in a deployed instance like tomcat, so let's see how to build the project and generate the ``.war`` file Build the .war -------------- The build process will generate a ``.war`` webapp file that can be deployed inside a tomcat container. Compile the first build to verify the project setup run the script ``build.sh`` .. code-block:: sh ./build.sh If everything is successful take the ``.war`` generated file and test it in a tomcat container Now: - rename the ``web/target/MyMapStoreProject.war`` file to ``mapstore.war`` - download tomcat - move the ``mapstore.war`` to the ``tomcat/webapps`` folder - start the tomcat container (startup.bat for Windows OS or startup.sh for unix OS) see the official documentation for additional information https://mapstore.readthedocs.io/en/latest/quick-start/#war-file The MapStore application run at: http://localhost:8080/mapstore You can use this tomcat instance as the backend of your local project. The downside of having it in an external tomcat container is that you have to build/deploy mapstore every time if you want to see changes applied By default the project created searches the backend at this url `http://localhost:8080/mapstore`, but you can change the whole `devServer` or only the `proxy` settings by passing `devServer` or `proxy` parameter of the `buildConfig` call function. .. note:: In the mapstore framework we use ``devServer.js`` file, that includes the default configuration of the dev-server. It is used by **build/webpack.config.js** and **build/prod-webpack.config.js**, that are the configuration files used by the dev and production build for webpack. MapStore2 submodule update --------------------------- Every project generated with ``createProject.js`` provides a ``MapStore2`` submodule folder that has a reference to a specific commit or branch of mapstore. The submodule is used by the project similarly to a node_modules packages with the difference to be able to apply changes to the submodule and send fixes to the MapStore2 repository/fork where needed. This setup allows to switch to a new version of ``MapStore2`` by following these steps: navigate to the MapStore2 folder .. code-block:: sh cd ./MapStore2 fetch the origin to get all the updated branches/commits .. code-block:: sh git fetch checkout to a specific branch/commit .. code-block:: sh git checkout origin/branch Now the MapStore2 submodule is updated to a specific branch and the project will use it as new package. It could be necessary to check migration guideline after switching to new branch to ensure a working project: - `mapstore migration guide `__ Best practices -------------- The project could have some misalignment with the default MapStore configuration in particular when migrating to new versions. Before to move on with next steps we suggests steps to check everything is aligned: - compare ``MyMapStoreProject/package.json`` with ``MyMapStoreProject/MapStore2/package.json`` in particular the devDependencies - remove the ``MyMapStoreProject/package-lock.json`` and ``MyMapStoreProject/node_modules`` and install the packages again. This is needed when updating the version of the MapStore submodule - compare ``MyMapStoreProject/web/pom.xml`` with ``MyMapStoreProject/MapStore2/java/web/pom.xml`` - compare ``MyMapStoreProject/configs/localConfig.json`` with ``MyMapStoreProject/MapStore2/web/client/configs/localConfig.json`` if it has been added to the project The list above shows the most common checks but based on the complexity of the project customization we could have additional files to compare.