.. _integrator_create_application: Create a new application ======================== Creating a new c2cgeoportal application is done by applying two Paste 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 `_, 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: \ pcreate -l You should at least see the c2cgeoportal scaffolds: * c2cgeoportal_create * c2cgeoportal_update Create the new application -------------------------- To create the application, first apply the ``c2cgeoportal_create`` scaffold: .. prompt:: bash docker run --rm -ti --volume=$(pwd):/src \ camptocamp/geomapfish-tools: \ run $(id -u) $(id -g) /src \ pcreate -s c2cgeoportal_create .. 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: \ run $(id -u) $(id -g) /src \ pcreate -s c2cgeoportal_create \ --package-name This will create a directory named ```` that will be next to the ``c2cgeoportal`` directory, or to the directory of the application you are creating this application from. Now apply the ``c2cgeoportal_update`` scaffold: .. prompt:: bash docker run --rm -ti --volume=$(pwd):/src \ camptocamp/geomapfish-tools: \ run $(id -u) $(id -g) /src \ pcreate -s c2cgeoportal_update .. 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. Go to your new project: .. prompt:: bash cd 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/.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-organisation 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-organisation 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 of the variables you have set as environment variables. The files can have the extension ``.tmpl`` and it use bash syntax (``${VARIABLE}``).