Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CircleCI BrowserStack Status codecov

Total alerts Language grade: Python Language grade: JavaScript

Maintainability Rating Quality Gate Status Reliability Rating Security Rating Technical Debt


geopuzzle Arrange the pieces of the world! You need to drag the shape of the territory to the right place. Just like in childhood we collected pictures piece by piece, so here you can collect a country from regions or whole continents from countries!

Furthermore second variation is the Quiz. In the Quiz you need find the country by flag, emblem or the capital.


This is just web application, so you need:

  1. nginx
  2. uwsgi
  3. supervisor
  4. python >= 3.8
  5. redis
  6. postgres >= 12
  7. nodejs >= 12.13

System applications

Install nginx, uwsgi, supervisor and other packages:

$ sudo apt install nginx uwsgi uwsgi-plugin-python3 supervisor redis-server
$ sudo apt install gdal-bin gettext build-essential python3-dev libpq-dev

Template config files for nginx, uwsgi and supervisor are placed in deploy directory. I hope python 3 with pipenv already installed :)

Create virtual environment

$ pipenv install

Create database

  1. Install Postgres with PostGIS:

    $ sudo apt install postgresql postgresql-contrib postgis
  2. Install postgis extension:

    $ sudo su postgres -c psql
    postgres=# create user geopuzzle with password 'geopuzzle';
    postgres=# create database geopuzzle owner geopuzzle;
  3. Create user and database:

    $ sudo su postgres -c psql
    postgres=# \c geopuzzle
    geopuzzle=# create extension postgis;
    geopuzzle=# create extension postgis_topology;
    geopuzzle=# create extension postgis_sfcgal;
    geopuzzle=# create extension fuzzystrmatch;
    geopuzzle=# create extension address_standardizer;
    geopuzzle=# create extension postgis_tiger_geocoder;
  4. Create .env file (based on .env_template) in project root with environment settings. Required parameters were already initialed default values in template file;

  5. Create tables:

    (venv)$ ./ migrate

Set up env variables

All environment variables are collected in .env file (.env_template is template for that). Some variables such as REDIS_HOST or DJANGO_SETTINGS_MODULE do not require explanation. But some are specific to the project:

  • OSM_KEY need only for load polygons into database
  • GOOGLE_KEY is production key for Google Maps API (preferred, but not required)
  • RAVEN_DSN for collect errors to Sentry (optional)
  • AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY need only for AWS settings usage. Can left them blank.

Build static files

Install nodejs:

$ sudo apt install nodejs npm
$ npm init
$ npm run build
(geopuzzle) $ ./ collectstatic

Load data

I find excellent service for load geojson files with polygons - Just select the country (or many or with regions) and click 'Export'. URL must be like:,-5682950&format=GeoJSON&srid=4326

And download content by that link. You've got zip archive with GeoJson files, unpack them into geojson folder. After that you can run management command (venv)$ ./ update_regions for load polygons into database. Take into account - data from OSM is not perfect and some regions can have bad or recursive links to each other. In most cases, restarting can help :)

Management commands

Management command usually run via script, for example: ./ import_region.

  • cache - import/export and recalculate cache (from postgres)
  • import_region - load one .geojson into database
  • update_infobox - update infobox from WikiData
  • update_regions - load all .geojson into database from geojson folder
  • validate_infoboxes - check that all required data in all infoboxes is filled and correct

Docker images

Project has 2 Dockerfiles:

  • /Dockerfile.backend - for server side (django tests and deploy)
  • /Dockerfile.frontend - for client side (webpack build bundles and jest tests for future)

All images should be up to date with all installed dependencies. This allows you to significantly reduce the time to perform tasks CI. Command for update image (frontend, by example):

$ docker build -t tyvik/geopuzzle:frontend -f Dockerfile.frontend .
$ docker push tyvik/geopuzzle:frontend

Run in dev mode with Docker Compose

Build and run:

$ docker-compose build
$ docker-compose up -d


$ docker-compose stop

You can download sample database. Unpack archive into pgdata directory.

Or download dump as sql file.

Go to http://localhost:8000

Useful links

Useful services

Browser Stack Logo