.. _integrator_create_application: Create a new application ======================== Creating a new c2cgeoportal application is done by applying two Cookiecutter scaffolds (a.k.a. templates and scaffolds). These scaffolds are provided by the ``c2cgeoportal`` package. So to be able to create a c2cgeoportal application the ``c2cgeoportal`` package must be installed. Project structure ----------------- In the simple case, the root directory of the application is the directory created by the c2cgeoportal scaffolds (the ``c2cgeoportal_create`` and ``c2cgeoportal_update`` scaffolds). Set environment variables ------------------------- For this procedure, we need to set some environment variables: .. prompt:: bash GEOMAPFISH_VERSION= GEOMAPFISH_PROJECT= GEOMAPFISH_PACKAGE= Where ```` can be found on :docker_hub:`Docker Hub `, is the project name that should be the GitHub repository name, is the package name. List existing scaffolds ----------------------- To list the available scaffolds, use the following command, either from the root directory of c2cgeoportal (if you have followed the instructions from the previous section), or from the root directory of the existing c2cgeoportal application you want to create the new application from: .. prompt:: bash docker run --rm \ camptocamp/geomapfish-tools:${GEOMAPFISH_VERSION} \ pcreate -l You should at least see the c2cgeoportal scaffolds: * c2cgeoportal_create * c2cgeoportal_update * c2cgeoportal_advance_create * c2cgeoportal_advance_update Create the new application -------------------------- To create the application (simple or advance), first apply the ``c2cgeoportal_create`` scaffold: .. prompt:: bash docker run --rm -ti --volume=$(pwd):/src \ camptocamp/geomapfish-tools:${GEOMAPFISH_VERSION} \ run $(id -u) $(id -g) /src \ pcreate --scaffold=create \ ${GEOMAPFISH_PROJECT} .. note:: Do not add any '/' after the project name. You will be asked to enter the SRID and the Apache vhost for this project. Note that the default extent would be defined directly from the SRID. You can change it later. .. note:: You can define this information directly in the command line using parameters: .. prompt:: bash docker run --rm -ti --volume=$(pwd):/src \ --env=SRID=2056 \ --env=EXTENT="2420000,1030000,2900000,1350000" \ camptocamp/geomapfish-tools:${GEOMAPFISH_VERSION} \ run $(id -u) $(id -g) /src \ pcreate --scaffold=create \ --package-name=${GEOMAPFISH_PACKAGE} \ ${GEOMAPFISH_PROJECT} This will create a directory named ```` in you current directory. For an advance application, apply the ``c2cgeoportal_advance_create`` scaffold: .. prompt:: bash docker run --rm -ti --volume=$(pwd):/src \ camptocamp/geomapfish-tools:${GEOMAPFISH_VERSION} \ run $(id -u) $(id -g) /src \ pcreate --scaffold=advance_create \ ${GEOMAPFISH_PROJECT} --overwrite Now apply the ``c2cgeoportal_update`` scaffold (for simple and advance applications): .. prompt:: bash docker run --rm -ti --volume=$(pwd):/src \ camptocamp/geomapfish-tools:${GEOMAPFISH_VERSION} \ run $(id -u) $(id -g) /src \ pcreate --scaffold=update \ ${GEOMAPFISH_PROJECT} --overwrite .. note:: Do not add any '/' after the project name. The ``c2cgeoportal_update`` scaffold is also used to update the application. The files generated by this scaffold are prefixed with ``CONST_``, which means they are *constant* files that should not be changed. Following this rule is important for easier updates. For an advance application apply the ``c2cgeoportal_advance_update`` scaffold: .. prompt:: bash docker run --rm -ti --volume=$(pwd):/src \ camptocamp/geomapfish-tools:${GEOMAPFISH_VERSION} \ run $(id -u) $(id -g) /src \ pcreate -s advance_update ${GEOMAPFISH_PROJECT} --overwrite Go to your new project: .. prompt:: bash cd ${GEOMAPFISH_PROJECT} For advance application you also should: Add an attribute ``advance: true`` in your ``project.yaml`` file. In the ``docker-compose.yaml`` file in the service ``geoportal`` you should replace ``service: geoportal`` by ``service: geoportal-advance``, and in service ``alembic`` you should replace ``service: alembic`` by ``service: alembic-advance``. Simple application ------------------ In contrast, a full application is an application for which the all possibilities for customization are made available, a simple application is an application for which no custom code is needed (Python or JavaScript). See also :ref:`integrator_structure` for more information. The documentation sections, in administrator and integrator guides, indicate whether the current section applies to the simple application mode or not. To convert an application to a simple application you should do: .. prompt:: bash git rm geoportal git checkout geoportal/vars.yaml git checkout geoportal/CONST_vars.yaml git checkout geoportal/CONST_config-schema.yaml git checkout geoportal/_geoportal/locale/ git checkout geoportal/_geoportal/static/ git rm CONST_create_template/geoportal git checkout CONST_create_template/geoportal/vars.yaml git checkout CONST_create_template/geoportal/CONST_vars.yaml git checkout CONST_create_template/geoportal/CONST_config-schema.yaml git checkout CONST_create_template/geoportal/_geoportal/locale/ git checkout CONST_create_template/geoportal/_geoportal/static/ You should also set an API name, in the ``vars.yaml`` file, in `vars/api/name`` and also modify the ``geoportal/_geoportal/static/apihelp/index.html`` file. Remove the attribute ``advance: true`` in your ``project.yaml`` file. Put the application under revision control ------------------------------------------ Now is a good time to put the application source code under revision control. To add a project in a new repository .................................... Add the project: .. prompt:: bash git init git remote add origin git@github.com:camptocamp/${GEOMAPFISH_PROJECT}.git Commit and push on the main repository: .. prompt:: bash git add . git commit -m "Initial commit" git push origin master Configuration of different environments in your project ------------------------------------------------------- Concepts ........ Application instances for different environments or for personal development should be configured through environment variables that are defined in the ``env`` files (file with default value: ``env.default``, file with project values: ``env.project``). Each environment can have its own ``env`` file (for example, development, integration, production). Whenever possible, it is strongly advised not to extend the ``vars.yaml`` file. We recommend instead that you use dynamic variables as described below. However, in some use cases extending ``vars.yaml`` may be needed: * Configuring highly specific environments * Configuration of a multi-organization project Use of dynamic variables ........................ Variables used in the application configuration files (files ``vars.yaml``) can be made dynamic by means of environment variable. For this, in the main file ``vars.yaml``, add a block ``runtime_environment`` at the bottom of the file. In this same file, you can change the value of a parameter by putting it in uppercase (example: ``host: '{HOST}'``). This parameter must be listed in the interpreted parameters section: .. code:: yaml extends: CONST_vars.yaml vars: host: '{HOST}' ... runtime_environment: - HOST In the ``env.project`` file, add parameters you want to change as exported variables: .. code:: HOST=domaine.different.com In the ``env`` file that extends this main file, you only need to define the environment variables: .. code:: HOST=prod.different.com Configure the application ------------------------- As the integrator, you need to edit the ``vars.yaml`` and ``env.project`` files to configure the application. Do not forget to add your changes to git: .. prompt:: bash git add vars.yaml env.project git commit -m "Configure the project" git push origin master .. note:: If you are using a multi-organization project, you should add all new children to the parent site check_collector configuration. After creation and minimal setup the application is ready to be installed. Then follow the sections in the install application guide: * :ref:`integrator_install_application_setup_database`. * :ref:`integrator_install_application_create_schema`. * :ref:`integrator_install_application_install_application`. .. note:: If you want a default theme, you can run: .. prompt:: bash docker compose exec geoportal create-demo-theme Dynamic configuration --------------------- Several files are generated on runtime, their content depending on the variables you have set as environment variables. The files can have the extension ``.tmpl`` and it use bash syntax (``${VARIABLE}``). GitHub workflows ---------------- With the application we have some predefined workflows. `.github/workflows/main.yaml` ............................. The workflow that will run on all your commits, it will: - Run some code style checks on your code. - Build you application. - Run the acceptance tests (if configured). - Publish the application on DockerHub. - Trigger another workflow (on ArgoCD repository) to deploy you new application. `.github/workflows/rebuild.yaml` ................................ This workflow run on each night to rebuild the application with the new version of the base images. Be careful, GitHub will read only the file present on the main branch. `.github/workflows/update_l10n.yaml` .................................... This workflow will query the `locale.pot` view, using `PROJECT_PUBLIC_URL` found in `Makefile`, and open a pull request to update the localization files (`.po`) with current list of translatable strings. Be careful, GitHub will read only the file present on the main branch. Acceptance tests ................ To have some acceptance tests you need to have a minimal dump of your database in the repository, it can be obtained with: .. prompt:: bash scripts/db-backup --arg=--schema= ../dump.backup In the `Makefile` you should configure the dump file as `DUMP_FILE`, the `db-restore` call in `acceptance-init` should probably also be updated. In the file `.github/workflows/main.yaml` you should uncomment all the lines related to the acceptance tests. The acceptance tests will test that we didn't have any service in error, test the response of some URL, see in the file `tests/test_app.py`.