This is a repository for 3D models and their metadata, for use by the community for improving the quality of 3D rendering of maps. The deployed version of the project can be experienced at 3dmr.
This project was originally developed as part of Google Summer of Code 2017 by Pedro Amaro, under the mentorship of the OpenStreetMap community with Jan Marsch and Tobias Knerr as mentors. The project was aimed at creating a repository for 3D models and their metadata, for use by the community for improving the quality of 3D rendering of maps.
The project requires Docker to be installed on the system. The following steps will guide you through setting up the development server.
- Clone the repository,
git clone https://github.com/fossgis/3dmr.git. - Move inside the directory that was created,
cd 3dmr. - Create .env file by copying the example file,
cp .env.example .env. - Make necessary changes in the .env file to set your environment variables.
- Make setup.sh executable,
chmod +x ./setup.sh. - Set up the container with
./setup.sh.
Your development server should now be running on port 8000.
- These are a set of simple step-by-step deployment instructions for 3dmr, to get the repository running on a server quickly. These steps have been tested in a fresh Debian 9 installation.
- Starting off, make sure to update your current packages:
# apt-get updateand# apt-get upgrade.- Download the required packages, in one go:
# apt-get install postgresql postgresql-client git python3 python3-pip apache2 libapache2-mod-wsgi-py3 python-virtualenv. Note: do not install python3-virtualenv, it won't work, python-virtualenv will work for both major versions of Python.
- Let's now set up PostgreSQL.
- Edit the file
/etc/postgresql/9.6/main/pg_hba.conf, addinglocal all 3dmr password, afterlocal all postgres peer, and then restart its service:service postgresql restart.- Switch to the postgres user:
su - postgres. The next few steps will be done in this user.- Create an user to use with the repository:
createuser -d -P 3dmr. Remember the password you enter here.- Create a new database for the repository, as the 3dmr user:
createdb -O 3dmr 3dmr.- Run
psql -d 3dmr -c "create extension hstore;"to activate the hstore extension on the database.- The database setup is now finished! Make sure to get back to the root user with
exit.
- We will now acquire the project from the git repository. This should be done with a separate user.
- Let's create it now:
# adduser tdmr(t stands for the t in three, as there can be no names starting with a digit).- Switch to the newly created user:
su - tdmr. The next commands will be run as this user.- In the home directory of this user, run
git clone https://github.com/fossgis/3dmr.git, then move inside it:cd 3dmr.- Setup the virtualenv:
virtualenv -p python3 .venv, and activate it:source .venv/bin/activate, and install the required Python packages:pip3 install -r requirements.txt.- We must now configure the model repository.
- With your favourite text editor, begin editing
.envfile. Then, in order, edit the folllowing variables:- Generate a new random
SECRET_KEY. This should be generated randomly, by a computer. One quick way to do this is runningimport binascii;import os;binascii.hexlify(os.urandom(50))in a Python shell.- Set
DEBUGtoFalse, as we're now in production.- You should also add your own OpenStreetMap OAuth key and secret, replacing
SOCIAL_AUTH_OPENSTREETMAP_KEYandSOCIAL_AUTH_OPENSTREETMAP_SECRET.If you do not have one, you can create it at https://www.openstreetmap.org/oauth2/applications.
- Configure the
POSTGRES_...entries: change the credentials as per the ones set in 2.3.- Finally, in
modelrepository/settings.py. SetALLOWED_HOSTSto['*']. IMPORTANT: You should replace this with['www.yourdomain.com']when you host it on a domain, or your public IP, according to https://docs.djangoproject.com/en/1.11/ref/settings/#allowed-hosts .- You can now save and close both the files.
Run
./manage.py migrateto create the tables for our database.Create a directory to hold the model zips:
mkdir ~/models. Configure the .env file, add at the end of the file:MODEL_DIR = '/home/tdmr/models'.Create a directory to hold the static files:
mkdir ~/staticand run./manage.py collectstaticto place the static files there.Set up the nightlies task, by placing the following script in
/home/tdmr/nightly.sh:#!/bin/bashcd /home/tdmr/3dmr/source .venv/bin/activate./manage.py nightlymv 3dmr-nightly.zip /home/tdmr/static/mainappand give it executable permissions:
chmod +x nightly.sh, and run it once, to set up an initial, empty, nightly zip:./nightly.sh.You should now be able to connect on port 8080 to the development server after running
./manage.py runserver 0.0.0.0:8080. Note that this will not yet work fully: static files will 404 (explaining the big avatar in the navbar if you login, or the missing model previews). Do not use this in production.
- Now, let's set up Apache.
Edit, as the root user,
/etc/apache2/sites-available/000-default.conf, adding at the end of the VirtualHost section:<VirtualHost *:80>Alias /static/ /home/tdmr/static/<Directory /home/tdmr/static>Require all granted</Directory><Directory /home/tdmr/3dmr/modelrepository><Files wsgi.py>Require all granted</Files></Directory>WSGIDaemonProcess 3dmr python-path=/home/tdmr/3dmr:/home/tdmr/3dmr/.env/lib/python3.5/site-packagesWSGIProcessGroup 3dmrWSGIScriptAlias / /home/tdmr/3dmr/modelrepository/wsgi.py</VirtualHost>Give Apache write permission to the model directory, by running
# chmod -R 0775 /home/tdmr/modelsand# chown -R :www-data /home/tdmr/models.Finally, restart Apache to update its settings:
# service apache2 restart
- The last remaining step is to set up the nightly script to run as a cronjob.
- Open the crontab, as the user
tdmr:# crontab -u tdmr -e.- Create an entry in the crontab for the nightly script, to run every day, at 4 AM:
0 4 * * * /home/tdmr/nightly.sh.- The 3D model repository has been successfully deployed!