Install an existing application¶
On this page we explain the procedure to build an application from only the current application code.
If you want to use an existing database, you should ignore all the commands concerning the database.
- This guide assumes that:
- all dependencies described in the requirements are installed,
- Git is used as revision control.
For specific environments, this page contains some notes to give some help.
Set up the database¶
Any c2cgeoportal application requires a PostgreSQL/PostGIS database. The application works with its own tables, which store users, layers, etc. These tables are located in a specific schema of the database.
Note
In a multi-project application architecture, multiple specific schemas must be used.
If the application has MapServer layers linked to PostGIS tables, these tables and the application-specific tables must be in the same database, preferably in separate schemas. This is required for layer access control (restricted layers), where joining user/role tables to PostGIS layer tables is necessary.
Create the database¶
To create the database you can use:
sudo -u postgres createdb <db_name> -T template_postgis
with <db_name>
replaced by the actual database name.
Note
If you do not have the template_postgis you can use:
with Postgres >= 9.1 and PostGIS >= 2.1:
sudo -u postgres createdb -E UTF8 -T template0 <db_name> sudo -u postgres psql -c "CREATE EXTENSION postgis;" <db_name>
with older versions:
sudo -u postgres createdb -E UTF8 -T template0 <db_name> sudo -u postgres psql -d <db_name> -f /usr/share/postgresql/9.1/contrib/postgis-2.1/postgis.sql sudo -u postgres psql -d <db_name> -f /usr/share/postgresql/9.1/contrib/postgis-2.1/spatial_ref_sys.sql
Note that the path of the postgis scripts and the template name can differ on your host.
If you wish to use the “similarity” function within the
full-text search, create the pg_trgm
extension:
sudo -u postgres psql -c "CREATE EXTENSION pg_trgm" <db_name>
Create the schemas¶
Each application needs two application-specific schemas. To create them, do:
sudo -u postgres psql -c "CREATE SCHEMA <schema_name>;" <db_name> sudo -u postgres psql -c "CREATE SCHEMA <schema_name>_static;" <db_name>
with <db_name>
and <schema_name>
replaced by the actual database name,
and schema name (‘main’ by default), respectively.
Note that if you are using a multi-project, you need to define both schemas
for the parent and for each child.
Create a database user¶
We use a specific user for the application, www-data
by default.
Note
It the user does not already exist in your database, create it first:
sudo -u postgres createuser -P <db_user>
Give the necessary rights to the user:
sudo -u postgres psql -c 'GRANT SELECT ON TABLE spatial_ref_sys TO "www-data"' <db_name> sudo -u postgres psql -c 'GRANT ALL ON TABLE geometry_columns TO "www-data"' <db_name> sudo -u postgres psql -c 'GRANT ALL ON SCHEMA <schema_name> TO "www-data"' <db_name> sudo -u postgres psql -c 'GRANT ALL ON SCHEMA <schema_name>_static TO "www-data"' <db_name>
Note
If you do not use the www-data
user for Apache, replace it by the right user.
Install the application¶
Get the application source tree¶
If GitHub is used for the application, use the following command to get the application source tree:
git clone git@github.com:camptocamp/<project>.git cd <project>
Non Apt/Dpkg based OS Configuration¶
For example Windows or RedHat.
Disable the package checking:
In the <package>.mk
add:
TEST_PACKAGES = FALSE
Windows Specific Configuration¶
Some Python modules cannot currently be installed through the Python Package Index (PyPI) and they have to be downloaded manually and stored. This is because these packages use DLLs and binaries which would have to be compiled using a C compiler.
Furthermore, some changes in the Apache WSGI and MapServer configurations are required to make c2cgeoportal work on Windows.
Also, between all the different command interfaces available on Windows (cmd, Cygwin, git mingw), only Windows default cmd interface handle paths correctly in all stage of the application setup.
Command interface and environment variable¶
Only use Windows default command interface:
Start > Run... > cmd
Cygwin and git mingw are not compatible. Powershell is untested.
In addition, you need to add all the resource paths to your system PATH environment variable, for cygwin, git and node binaries.
Python Wheels¶
You should create a “wheels” folder at the root folder of your project.
Then, go to http://www.lfd.uci.edu/~gohlke/pythonlibs/, search and download the following packages:
- Psycopg2
- Shapely
- Pillow
- Pyproj
If your project is configured for Windows, then make
will expect this folder
to exist and to contain these wheels.
mapserver/mapserver.map.mako¶
You must specify the path to the MapServer’s EPSG file by uncommenting and adapting
this line under MAP
(use regular slash /
)
PROJ_LIB" "C:/PATH/TO/ms4w/proj/nad"
<project>.mk¶
The following configuration override must be added to your <project>.mk
:
# Sets that is we use Windows
OPERATING_SYSTEM ?= WINDOWS
# Path to cygwin
CYGWIN_PATH ?= c:/path/to/cygwin
RedHat Specific Configuration¶
Specific settings are required when the c2cgeoportal application is to be run on RedHat Enterprise Linux (RHEL) 6.
Note
First of all, note that, with RHEL, you cannot install the c2cgeoportal application in your homedir. If you do so, you will get the following error in the Apache logs:
(13)Permission denied: access to /~<your_user_id>/ denied
So always install the application in an Apache-accessible directory. On
Camptocamp puppetized servers you will typically install the application
in /var/www/vhosts/<vhost>/private/dev/<username>/
, where <vhost>
is the name of the Apache virtual host, and <username>
is your Unix
login name.
apache/application.wsgi.mako¶
Ensure that the regular expression used in apache/application.wsgi.mako
to modify the sys.path
matches the system directories containing python packages. If you are installing from scratch, this should
already be the case; otherwise look at scaffolds/create/apache/application.wsgi.mako
for an example.
Install the application¶
You can build and install the application with the command:
./docker-run make --makefile=<user>.mk build
This previous command will do many things like:
- adapt the application configuration to your environment,
- build the JavaScript and CSS resources into compressed files.
Then create the application tables:
./docker-run make --makefile=<user>.mk upgrade-db
For non Docker installation:
FINALISE=TRUE make --makefile=<user>.mk build
This previous command will do many things like:
- download and install the project dependencies,
- deploy the MapFish Print service if it is configured for building.
Your application should now be available at:
https://<hostname>/
,
where the <hostname>
is directly linked to the virtual host.
Add in the /var/www/vhosts/<vhost_name>/conf/proxies.conf
file
(create it if it does not exist):
ProxyPass "/<instance>" "http://localhost:8080/<instance>"
ProxyPassReverse "/<instance>" "http://localhost:8080/<instance>"
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"
ProxyRequests Off
The root instance should be at the end.
Migrating to a new server¶
If you are migrating to a new server, keep in mind that your variable
VISIBLE_WEB_HOST
must contain the exact host name that browsers should use
to access your site. Consider the following migration scenario:
your current site runs on server old-site.customer.ch
with the visible host name
gis.customer.ch
. You wish to setup a new server new-site.customer.ch
,
install the application and test it, and then switch your DNS so that
gis.customer.ch
now points to new-site.customer.ch
.
To accomplish this, you must proceed as follows:
- set
VISIBLE_WEB_HOST
tonew-site.customer.ch
- install the application on
new-site.customer.ch
and test the application athttp://new-site.customer.ch
- later, when going live, you must:
- change
VISIBLE_WEB_HOST
togis.customer.ch
- re-build, re-deploy - but do not test yet!
- change your DNS so that
gis.customer.ch
points tonew-site.customer.ch
.- Now test your new live site.