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:

GEOMAPFISH_VERSION=<release>
GEOMAPFISH_PROJECT=<project>
GEOMAPFISH_PACKAGE=<package>

Where <release> can be found on Docker Hub, <project> is the project name that should be the GitHub repository name, <package> 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:

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:

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:

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 <project> in you current directory.

For an advance application, apply the c2cgeoportal_advance_create scaffold:

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):

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:

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:

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 Project 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:

git rm geoportal
git checkout geoportal/vars.yaml
git checkout geoportal/CONST_vars.yaml
git checkout geoportal/CONST_config-schema.yaml
git checkout geoportal/<project>_geoportal/locale/
git checkout geoportal/<project>_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/<project>_geoportal/locale/
git checkout CONST_create_template/geoportal/<project>_geoportal/static/

You should also set an API name, in the vars.yaml file, in vars/api/name` and also modify the geoportal/<package>_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:

git init
git remote add origin git@github.com:camptocamp/${GEOMAPFISH_PROJECT}.git

Commit and push on the main repository:

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:

extends: CONST_vars.yaml

vars:
    host: '{HOST}'
...
runtime_environment:
    - HOST

In the env.project file, add parameters you want to change as exported variables:

HOST=domaine.different.com

In the env file that extends this main file, you only need to define the environment variables:

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:

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:

Note

If you want a default theme, you can run:

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:

scripts/db-backup --arg=--schema=<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.

Create a new application¶

Project structure¶

Set environment variables¶

List existing scaffolds¶

Create the new application¶

Simple application¶

Put the application under revision control¶

To add a project in a new repository¶

Configuration of different environments in your project¶

Concepts¶

Use of dynamic variables¶

Configure the application¶

Dynamic configuration¶

GitHub workflows¶

.github/workflows/main.yaml¶

.github/workflows/rebuild.yaml¶

.github/workflows/update_l10n.yaml¶

Acceptance tests¶

c2cgeoportal

Navigation

Related Topics