Welcome to TerraVisu’s documentation!
Install instructions
Requirements
- You need docker installed. Compose plugin is recommended in the configuration below.
See Docker.
Optional : if you want to use external database, prepare a postgresql 11+ (15 recommended) postgis2.5 (3.3 recommended) database with postgis enabled, and a dedicated user.
- You can use external database by commenting postgres container and volume references in docker-compose.yml, and set variables in your conf/visu.env file :
POSTGRES_HOST
POSTGRES_PORT
POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_DB
Add local IPs in pg_hba.conf to allow connection from docker containers to your database.
You can use external nginx proxy. Edit provided nginx conf file and comment nginx references in docker-compose.yml. Fix web:8000 to 127.0.0.1:8000 in nginx.conf.
Install
Download zip package
Unzip it where you want
unzip install.zip cd terra_visu
Prepare environment variables
./conf/visu.env
-> Set or change all required values
at least:
ALLOWED_HOST # list of your final host(s), comma separated values
SECRET_KEY # unique key for your project. See https://djecrety.ir/
POSTGRES_USER # a dedicated user for your database
POSTGRES_PASSWORD # a dedicated password for your database
Pull images
docker compose pull
Init database and project config
docker compose run --rm web update.sh
Create your super user
docker compose run --rm web ./manage.py createsuperuser
Load initial data
docker compose run --rm web ./manage.py loaddata project/fixtures/initial.json
Launch stack
docker compose up -d
… and access to TerraVisu
http://<your_domain>/
You can change port mapping by using a .env file in terra_visu directory :
# .env NGINX_PORT=8080
Update
Read release notes about bugfix, news and breaking changes.
Backup your data (database, public/media and var/ folder)
Pull latest image
docker compose pull
Run post update script
docker compose run --rm web update.sh
Relaunch your stack
docker compose down docker compose up -d
Configuration
Environment variables
Add your environment variables in app.env file.
General
- ALLOWED_HOSTS
domains allowed to be used by your instance. Support comma separated values.
Example:
ALLOWED_HOSTS=mysite.fr # ALLOWED_HOSTS=mysite.fr,my.other.site.fr
- SECRET_KEY
unique secret key for your instance. (https://djecrety.ir/)
Example:
SECRET_KEY=zbesj@t3_&u75&l=xk@ftg1yh4wy)i)9!z+(v$ig7*-*lkd6om
- SSL_ENABLED
Set true if your site is behind ssl proxy.
Example:
SSL_ENABLED=True
Default:
False
OIDC Connect
To allow OIDC login, you should configure these settings.
- OIDC_ENABLE_LOGIN
Enable OIDC connect login.
Example:
OIDC_ENABLE_LOGIN=True
Default:
False
- OIDC_DISABLE_INTERNAL_LOGIN
Disable internal login if OIDC enabled. (direct redirection to OIDC login)
Example:
OIDC_DISABLE_INTERNAL_LOGIN=True
Default:
False
- OIDC_AUTH_SERVER
Set your OIDC Realm URL.
Example:
OIDC_AUTH_SERVER=https://your.openid.com/realms/master
- OIDC_AUTH_CLIENT_ID
Set your OIDC Client ID.
Example:
OIDC_AUTH_CLIENT_ID=your-client-id
- OIDC_AUTH_CLIENT_SECRET
Set your OIDC Client secret.
Example:
OIDC_AUTH_CLIENT_SECRET=7GcKm7XiWIE6BRscGHZZku
- OIDC_AUTH_SCOPE
Set your OIDC Client scope. Support comma separated values.
Example:
OIDC_AUTH_SCOPE=openid,email
Default:
openid
SENTRY
- SENTRY_DSN
Set your SENTRY_DSN to enable sentry reporting.
Example:
SENTRY_DSN=https://your.sentry/dsn
Default:
None
- SENTRY_TRACE_SAMPLE_RATE
Specify sample rate for your performance tracking.
Example:
SENTRY_TRACE_SAMPLE_RATE=1.0
Default:
0.2
- SENTRY_SEND_DEFAULT_PII
Specify if sentry enable user informations.
Example:
SENTRY_SEND_DEFAULT_PII=False
Default:
True
API Schemas
- API_SCHEMA
Set true if you want to expose API openapi schema. It expose /api/schema/ endpoint.
Example:
API_SCHEMA=True
Default:
False
- API_SWAGGER
Set true if you want to expose API swagger. API_SCHEMA should be enabled. It expose /api/schema/swagger/ endpoint.
Example:
API_SWAGGER=True
Default:
False
- API_REDOC
Set true if you want to expose API redoc. API_SCHEMA should be enabled. It expose /api/schema/redoc/ endpoint.
Example:
API_REDOC=True
Default:
False
Usage
Configure instance settings
Need to have SuperUser privileges
Go to /config/
Sources, layers and views
Need to have required privileges
Go to /admin/
Configure map base layers
Add data sources
Configure views and layers
Development
Prepare stack
cp db.env.dist db.env
cp app.env.dist app.env
docker-compose build
Init database
docker-compose run --rm web ./manage.py migrate
Load initial data
docker-compose run --rm web ./manage.py loaddata project/fixtures/initial.json
Create your superuser
docker-compose run --rm web ./manage.py createsuperuser
Launch stack
docker-compose up
Then go to http://visu.localhost:8080
Use admin
make build_admin
Then go to http://visu.localhost:8080/admin/
Development
Elastic search container doesn’t start
If you have:
bootstrap check failure [1] of [1]: max virtual memory areas vm.max_map_count [xxx] is too low, increase to at least [yyy]
Then you need to increase the vm.max_map_count on your host machine.
..code-block:: bash
sudo nano /etc/sysctl.conf
vm.max_map_count to 262144.
Then reboot your machine.
CHANGELOG
2023.4.1 (2023-04-07)
New Version
New Simplified Installation
New documentation
Bug fixes:
Fix and allow date usage in source fields and imported data
Fix group creation / edition in admin
Fix LayerTree cache management
Fix bug when no base layer defined in scene (#109)
New features:
Use icon and patterns in point / polygon styles
Improvements:
Direct use elasticsearch connector for data indexation instead of terra-bonobo-nodes
Better layer duplication
Some instance configuration managed in config panel (/config/)
Maintenance
From Python 3.6 to 3.10
From Django 2.2 to 4.1
All python packages updated
Admin node-js from 12 to 18