Installation without docker

Duration: 30-45 minutes.

This tutorial covers setting up a running LocalCosmos Private Server as a development server. This tutorial is intended for people not familiar with django. For more information about django visit https://www.djangoproject.com/ .

1. Prerequisites

Before you can install django and the localcosmos_server package, you have to install the requirements below. All code examples are for Debian/Ubuntu based systems.

1.1 Required server components

On Debian/ubuntu, you can install the required packages as follows:

sudo apt-get install nginx
sudo apt-get install python3 python3-dev
sudo apt-get install virtualenv
sudo apt-get install postgresql-10 postgresql-10-postgis-2.4 libpq-dev postgresql-server-dev-10

1.2 Create Postgres database

If not yet done, create a postgres database. If your desired database name is localcomsos, you can create the database as follows:

sudo -u postgres -i
psql
# create new database by the name localcosmos
create database localcosmos;

You also have to create a database user which has the right to alter the just created localcosmos database. In this example the user is named lcuser, but you can use any other name. You have to replace <lcpassword> with your desired password.

create user lcuser;
alter role lcuser SUPERUSER;
alter user lcuser PASSWORD '<lcpassword>';
\q

1.3 Install the kmeans PostgreSQL extension

1.3.1 Switch back to your server user

This step only applies if you follow this tutorial step by step. Switch back from the postgres user to the user you use on your server. Replace <serveruser> with the username you use on your server.

su <serveruser>

1.3.2 Download kmeans

Download and unzip https://github.com/umitanuki/kmeans-postgresql on your server. In this example, kmeans is downloaded into /opt/kmeans, but you can use any other folder.

sudo mkdir /opt/kmeans
cd /opt/kmeans
# replace <serveruser> with your username
sudo chown <serveruser>:<serveruser> /opt/kmeans
wget https://github.com/umitanuki/kmeans-postgresql/archive/master.zip
# install unzip
sudo apt-get install unzip
unzip master.zip

1.3.3 Activate kmeans extension

In this example, the database which we want to install the kmeans extension for, is named localcosmos. Replace localcosmos if your database has a different name.

cd /opt/kmeans/kmeans-postgresql-master
# if not yet done, install build requirements
sudo apt-get install make gcc
# make and make install kmeans
make
sudo make install
# switch to the postgres user
sudo -u postgres -i
# activate the kmeans extension for the database localcosmos, replace the db name if necessary
psql -f /usr/share/postgresql/10/extension/kmeans.sql -d localcosmos
exit

2. Create a new django project

Create a project folder

Create a folder on your disk where your Local Cosmos Private Server can live. eg: /opt/localcosmos. Make sure you have permissions to write this folder. In the example the server user is <serveruser> - replace this with the username you use.

Create a python3 virtual environment

sudo mkdir /opt/localcosmos
sudo chown <serveruser>:<serveruser> /opt/localcosmos
cd /opt/localcosmos
virtualenv -p python3 venv

Activate the virtual environment

source venv/bin/activate

Install django and localcosmos_server

pip install django==2.2.*
pip install localcosmos_server

This will install django, localcosmos_server and its requirements in your created and activated virtualenv.

Create a new django project

In /opt/localcosmos execute the following:

django-admin startproject localcosmos_private

This will automatically create the folder /opt/localcosmos/localcosmos_private, which contains your newly created django project.

3. Configure your django project

3.1 settings.py

You now have to adjust the contents of the file settings.py located in /opt/localcosmos/localcosmos_private/localcosmos_private/ to set up your LocalCosmos Private Server.

Replace INSTALLED_APPS with the following:

INSTALLED_APPS = [

        # django defaults
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',

        # localcosmos
        'django.contrib.sites',

        'localcosmos_server',
        'localcosmos_server.app_admin',
        'localcosmos_server.server_control_panel',
        'localcosmos_server.datasets',
        'localcosmos_server.online_content',

        'django_road',
        'anycluster',
        'content_licencing',

        'rules',
        'el_pagination',
        'django_countries',
        'corsheaders',
        'rest_framework',
        'rest_framework.authtoken',

        'octicons',
        'imagekit',

        'django.forms',
]

Replace the MIDDLEWARE setting with the following

MIDDLEWARE = [
        'localcosmos_server.middleware.LocalCosmosServerSetupMiddleware', # has to be on top
        'django.middleware.security.SecurityMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        'django.middleware.locale.LocaleMiddleware',
        'corsheaders.middleware.CorsMiddleware',
        'django.middleware.common.CommonMiddleware',
        'django.middleware.csrf.CsrfViewMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.messages.middleware.MessageMiddleware',
        'django.middleware.clickjacking.XFrameOptionsMiddleware',
        'localcosmos_server.app_admin.middleware.AppAdminMiddleware',
        'localcosmos_server.server_control_panel.middleware.ServerControlPanelMiddleware',
]

Replace the TEMPLATES setting with the following

TEMPLATES = [
        {
                'BACKEND': 'django.template.backends.django.DjangoTemplates',
                'DIRS': [],
                'APP_DIRS': False,
                'OPTIONS': {
                    'context_processors': [
                        'django.template.context_processors.debug',
                        'django.template.context_processors.request',
                        'django.contrib.auth.context_processors.auth',
                        'django.contrib.messages.context_processors.messages',
                        'localcosmos_server.context_processors.localcosmos_server',
                    ],
                    'loaders' : [
                        'django.template.loaders.filesystem.Loader',
                        'django.template.loaders.app_directories.Loader',
                    ]
                }
        },
]

Set up the database. Replace the DATABASE``setting with the setting below. Make sure you replace ``<lcpassword> with the correct password. If you did not follow the Preparing your webserver tutorial, you will also have to adjust the NAME and USER paramters according to your postgresql database name and your postgresql username.

DATABASES = {
        'default': {
                'ENGINE': 'django.contrib.gis.db.backends.postgis',
                'NAME': 'localcosmos',
                'USER' : 'lcuser',
                'PASSWORD' : '<lcpassword>',
                'HOST' : 'localhost',
        }
}

Replace ALLOWED_HOSTS with the following.

ALLOWED_HOSTS = ['localhost']

Replace or add STATIC and MEDIA paths

STATIC_URL = '/static/'
STATIC_ROOT = '/var/www/localcosmos/static/'

MEDIA_ROOT = '/var/www/localcosmos/media/'
MEDIA_URL = '/media/'

Inlude localcosmos_server settings in your settings.py file. This automatically covers anycluster, django_road and cors settings. Insert these lines at the bottom of settings.py

from localcosmos_server.settings import *

# location where apps are installed
# your apps index.html will be in LOCALCOSMOS_APPS_ROOT/{APP_UID}/www/index.html
LOCALCOSMOS_APPS_ROOT = '/var/www/localcosmos/apps/'

3.2 urls.py

The file urls.py located in /opt/localcosmos/localcosmos_private/localcosmos_private/ also needs configuration. You urls.py should look like this:

from django.conf import settings
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
        path('admin/', admin.site.urls),
        path('', include('localcosmos_server.urls')),
]

As long as you run the django development server, add the following at the bottom of urls.py.

# remove these lines after development
if settings.DEBUG:
        from django.conf.urls.static import static
        urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Make sure your remove these lines before deploying django. For better security, static and media files should be served directly by nginx in a production environment.

That’s it for the django configuration.

4. Migrate database

In your django project directory, /opt/localcosmos/localcosmos_private/, run

python manage.py migrate

to migrate the database.

5. Create localcosmos www folder

We need the folder /var/www/localcosmos and django has to be able to write into it. Replace <server_user> with the user you use on your computer.

# if the folder does not exist yet
sudo mkdir /var/www/localcosmos
# run this command in any case
sudo chown <server_user>:www-data /var/www/localcosmos

6. Run the development server

In your django project directory, /opt/localcosmos/localcosmos_private/, run the following command to start the development server.

python manage.py runserver 0.0.0.0:8080

Now open a browser and navigate to http://localhost:8080 . Follow the instructions to complete the setup.

Also check if the API works. Browse to http://localhost:8080/api/ .

After you completed the setup, the Server Control Panel ist available at http://localhost:8080/server/control-panel/.

7. Re-running the development server

If you want to start the development server after rebooting, you have to activate the virtual environment first.

cd /opt/localcosmos
source venv/bin/activate
cd localcosmos_private
python manage.py runserver 0.0.0.0:8080