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:

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

Create the new application

To create the application, 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 -s c2cgeoportal_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 -s c2cgeoportal_create \
    --package-name ${GEOMAPFISH_PACKAGE} ${GEOMAPFISH_PROJECT}

This will create a directory named <project> 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:

docker run --rm -ti --volume=$(pwd):/src \
    camptocamp/geomapfish-tools:${GEOMAPFISH_VERSION} \
    run $(id -u) $(id -g) /src \
    pcreate -s c2cgeoportal_update ${GEOMAPFISH_PROJECT}

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:

cd ${GEOMAPFISH_PROJECT}

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 create a simple application you should:

  • Add the image to the geoportal and alembic service in the docker-compose.yaml: image: camptocamp/geomapfishapp-geoportal:${GEOMAPFISH_MAIN_VERSION}.

  • Add the following lines in the .gitignore file:

# Simple mode
/geoportal/*
!/geoportal/vars*.yaml
!/geoportal/CONST_vars.yaml
!/geoportal/CONST_config-schema.yaml
!/geoportal/geomapfish_geoportal
/geoportal/geomapfish_geoportal/*
!/geoportal/geomapfish_geoportal/locale/
!/geoportal/geomapfish_geoportal/static/

/CONST_create_template/geoportal/*
!/CONST_create_template/geoportal/vars*.yaml
!/CONST_create_template/geoportal/geomapfish_geoportal
/CONST_create_template/geoportal/geomapfish_geoportal/*
!/CONST_create_template/geoportal/geomapfish_geoportal/locale/
!/CONST_create_template/geoportal/geomapfish_geoportal/static/

Note

If you apply those steps on a project already committed on Git, you should also remove all the ignored files.

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 of the variables you have set as environment variables.

The files can have the extension .tmpl and it use bash syntax (${VARIABLE}).