Setup Development Environment

Warning

Current instructions are not working. Will fix as an URGENT task

These instructions will help you install a development environment. Setup is slightly different to a production environment.

It is recommended to install NearBeach on a Long Term Support (LTS) version of Django. Security fixes/patches are applied for a longer period of time, helping keep your server secure.

NearBeach currently supports the following Django versions;

  • Django Version 3.1

More information about upgrading Django can be found found in the Django Documentation

Note

The following instructions are for Ubuntu 18.04. If you are using a different operating system, modify the instructions to suit that operating system.

Download Git Repository

  1. In a terminal, navigate to your project development folder
cd /<<project-dev-folder>>
  1. Use Git to download NearBeach source code
git clone https://github.com/robotichead/NearBeach
  1. First update and upgrade the system so you are working with the latest packages;
sudo apt-get update && sudo apt-get upgrade -y
  1. Next we will need to install all the packages we will use in NearBeach
sudo apt install python3-dev libpq-dev nginx curl build-essential python3-setuptools libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
  1. Install pip
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
sudo python3 get-pip.py
  1. After installing the required packages, you will need to update pip
sudo pip3 install --upgrade pip
  1. Once pip is upgraded, you will need to create a virtual environment
sudo pip3 install virtualenv
  1. Create your own virtual environment for python
virtualenv <<project_environment>>

This will create a directory called “<<project_environment>>”, this will store NearBeach’s libraries for python

  1. Activate the virtual environment using the following command
source ./<<project_environment>>/bin/activate

You terminal prompt will change to indicate that it is working in the virtual environment now. It should look like the following

(<<project_environment>>)user@computer:
  1. Install Django
pip install django
  1. Adjust the project’s settings to allow debugging and accept ALL allowed hosts
nano ./<<django_project>>/<<django_project>>/settings.py
  1. Change the following lines to reflect the following

..image:: images/django-installation-001.png

This will allow us to test the web server. We will be modifying this file later to be more security conscience

Save the settings file and exit

  1. Run the following command to see if Django is running
python3 ./manage.py runserver

If the server runs fine - then we can proceed.

  1. Symbolic link in NearBeach’s source code
ln -s /<<project-dev-folder>>/NearBeach/NearBeach /<<project-dev-folder>>/<<django_project>>

This code will place the core NearBeach code into the Django’s project directory.

  1. Navigate to your project’s folder
$ cd <<django_project_location>>
  1. Install all required python files using pip
pip3 install -r ./NearBeach/requirements.txt
  1. Edit the project’s settings.py to include NearBeach
$ nano ./<<project name>>/settings.py
  1. Add the following line to the “INSTALLED_APPS” section
'NearBeach.apps.NearBeachConfig',
'django.contrib.humanize',
'tinymce',
'django_select2',

Now save the document

  1. Email - optional however required for resetting passwords
$ nano ./<<project name>>/settings.py

Add the following lines of code into the settings.py

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_USE_TLS = True
EMAIL_HOST = '<< your email host >>'
EMAIL_PORT = 25
EMAIL_HOST_USER = '<< your username >>'
EMAIL_HOST_PASSWORD = '<< your password >>'
DEFAULT_FROM_EMAIL = EMAIL_HOST_USER
  1. Private Documents
nano ./<<project name>>/settings.py

Add the following lines of code into the settings.py

PRIVATE_MEDIA_URL = '/private/' #Can change
if DEBUG:
    # dev
    import os

    PROJECT_PATH = os.path.abspath(os.path.dirname(__file__))
    PRIVATE_MEDIA_ROOT = os.path.join(PROJECT_PATH, 'private')
    PRIVATE_MEDIA_SERVER = 'DefaultServer'
else:
    # prod
    PRIVATE_MEDIA_ROOT = '<< private documents location >>'
    PRIVATE_MEDIA_SERVER = 'ApacheXSendfileServer'

The following redundant code will need to be used at the moment.

STATIC_URL = '/static/'
STATIC_ROOT= os.path.join(BASE_DIR,'static/')
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR,'media/')
  1. Edit the project’s URL.py to include NearBeach
nano ./<<project name>>/url.py

Please make sure that the following import in included at the top of the file

from django.urls import path, include

Either of the following can be entered into the “urlpatterns” section

path('', include('NearBeach.urls')),
path('tinymce/', include('tinymce.urls')),
path('select2/', include('django_select2.urls')),
  1. Create Database/Migrations

The database will need to be setup. Please note by default Django uses sqlite3, however it is possible to setup NearBeach to use a mysql database.

python ./manage.py migrate
python ./manage.py migrate NearBeach

If you have setup NearBeach with an SQLite database, you will need to change it’s permissions so nginx can access it

sudo chmod 7777 ./db.sqlite
  1. Create superuser

A superuser will need to be created. This superuser will be able to enter the ADMIN site of Django, which from there will be able to do administration items.

python ./manage.py createsuperuser

Enter in the correct details for the superuser

  1. Collect the static

The website uses static images, javascript, and CSS. You will need to collect this data to the static folder (set in the settings.py). Please run the following command

python ./manage.py collectstatic
  1. Create the private media folder
$ mkdir ./private_media/

The NearBeach development environment should now be setup on your local.

Note

The first user to log in will automatically get administration permissions. It is recommended to get the system admin to log in first before importing any user data from other sources. This also allows the admin to setup groups and permissions.