Tendenci can be installed in two ways. The first is a quick and easy setup for development and basic testing, the second is a more scalable aproach for live deployments where the heavy lifting is done by services other than the Django built in web server.

Since the second category is effectively an extension of the first both sets of instructions are presented below.

These instructions create a Tendenci site on an Ubuntu server (14.04 is recommended).

Testing Installation

You can use the following installation instructions to install a local Tendenci site on Ubuntu (deb). This Django project is intended to help create a Tendenci site that you can deploy on a public hosting, but it’s recommended that you install locally first in order to test your themes and designs.

If working on a Mac or PC, or even Ubuntu, we strongly recommend using VMWare Fusion, or at least VirtualBox at a minimum to test different configurations. (Hint: VMWare handles bridge IPs much better than VirtualBox which matters if you travel a lot and bounce between networks like us.)

System requirements

The following are recommended system specifications for a server that will run a test tendenci install.

  • 1 CPU core for every 2 django workers
  • 2GB of RAM (Relying on swap will hurt performance)
  • 3GB of storage

These values are minimums and its recommended you use at least double the minimum CPU cores and storage.

System update

Before installing it is recommended you update your system to ensure you have the latest packages. For Ubuntu this is done by

sudo apt-get update
sudo apt-get dist-upgrade

Required Dependencies

You’ll need those packages installed on Ubuntu.

sudo apt-get install build-essential python-dev libevent-dev libpq-dev libjpeg8 libjpeg-dev libfreetype6 libfreetype6-dev

You’ll also need to have Git set up (see this Github help article for instructions).

sudo apt-get install git

To configure your system to automatically install security updates, run the following commands.

sudo apt-get install unattended-upgrades update-notifier-common
sudo dpkg-reconfigure -plow unattended-upgrades

Note: Say ‘Yes’ when it asks about security updates. Without security we have nothing.

Pip Install

Depending on your version of python pip is installed differently. If your system is python 2.7.9 or later pip can be installed with:

sudo apt-get install python-pip

If your system is pre Python 2.7.9 you will need to install pip from the Internet. The following command will download and install pip and its dependencies for you.

wget https://bootstrap.pypa.io/get-pip.py -O - | sudo python

Virtualenv install

Once pip is installed you can continue to install virtualenv:

sudo pip install virtualenv

OS X specific

This section includes the entire install process for Mac OS X. Once you have installed Virtualenv, create a virtualenv inside your project top folder. You can name your virtualenv whatever you like, in this example, we used “venv.”

virtualenv -p venv

Note: If you have anaconda installed on your machine, you would have to specify the path where the version of python is that you would like to use.

virtualenv -p /Library/Frameworks/Python.framework/Versions/2.7/bin/python2 venv

To activate the Virtualenv

source venv/bin/activate

Note: When you’re ready to get out of the Virtualenv simply use the command:

deactivate

Once inside your VirtualEnv, install Tendenci with PyPy by using the pip command below (you can learn more about PyPy packages at: http://packages.pypy.org/ :

pip install tendenci

Noted in a separate section of the docs, you can get setup quickly with the Postgres App. We strongly recommend checking out their documentation for help. For documentation on their App check out: https://postgresapp.com/.

You can “enter” Postgres with the command line

psql

One in Postgres, add a project, user, and password

CREATE DATABASE myproject;
CREATE USER myprojectuser WITH PASSWORD 'password';

ALTER ROLE myprojectuser SET client_encoding TO 'utf8';
ALTER ROLE myprojectuser SET default_transaction_isolation TO 'read committed';
ALTER ROLE myprojectuser SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE myproject TO myprojectuser;

To exit:

\q

You can also alter your database entirely from the command line using these commmands:

sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION postgis;"
sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION postgis_topology;"
sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION fuzzystrmatch;"
sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION postgis_tiger_geocoder;"

Or this

psql -h localhost -d $DB_NAME -c "CREATE EXTENSION postgis;"
psql -h localhost -d $DB_NAME -c "CREATE EXTENSION postgis_topology;"
psql -h localhost -d $DB_NAME -c "CREATE EXTENSION fuzzystrmatch;"
psql -h localhost -d $DB_NAME -c "CREATE EXTENSION postgis_tiger_geocoder;"

Next, to start your Tendenci project

sudo django-admin.py startproject --template=https://github.com/tendenci/tendenci-project-template/archive/master.zip    myproject
cd myproject
sudo pip install -r requirements/dev.txt

cd ..

Change to your top-level directory where “myproject” and “venv” are. In order for images to correctly render, you will need to install the jpeg libraries with the commands below

curl -O http://www.ijg.org/files/jpegsrc.v9.tar.gz
tar -xvzf jpegsrc.v9.tar.gz
cd jpeg-9
./configure
make
sudo make install

To remove the files

cd ..
rm -r jpeg-9
rm jpegsrc.v9.tar.gz

On Mac OS X 10.7 or higher you will need Xcode 4.4.1 or higher (in app store) and will need to install the Command Line tools it comes with. To install these, open Xcode, click the “Xcode” menu item in the top left of the screen near the Apple logo, then click “Preferences”, then click “Downloads”. Then click install on the line next to Command Line Tools.

Next, configure your database in local_settings.py

cd myprojectfolder/conf
sudo nano local_settings.py

Set up the following:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'myproject',
        'USER': 'myprojectuser',
        'PASSWORD': 'password',
        'HOST': 'localhost',
        'PORT': '',
    }
}

Then migrate and deploy your project

python manage.py migrate
python deploy.py
python manage.py runserver

And finally load the default

python manage.py load_creative_defaults
chmod -R -x+X media

Then create a superuser to login!

python manage.py createsuperuser
python manage.py runserver

To exit the server

^C

To add the tendenci code base to your local machine, pull down forked version to be able to submit pull requests on github. Add above project folder, go to python packages and delete the tendenci folder then generate a symlink to the github repo

Here’s how to delete the current tendenci folder

cd /Users/myusername/myprojectname/venv/lib/python2.7/site-packages
rm -rf tendenci

To create a symlink, then

ln -s /Users/myusername/myprojectname/code/tendenci/tendenci .

Setting up the database

Tendenci is designed for use with PostgreSQL. You will need to have a PostgreSQL server you can connect your tendenci install too. Instructions are provided for OSX and Ubuntu below or for more on installing PostgreSQL for Django check the docs at https://docs.djangoproject.com/en/dev/ref/databases/#postgresql-notes.

OS X

If you are on OS X, we recommend Postgres.app to get up and running fast.

With Postgres installed, you can create a database from Terminal (replace <DB_NAME> with your database name):

DB_NAME=<DB_NAME>
psql -h localhost -c "CREATE DATABASE $DB_NAME"
psql -h localhost -d $DB_NAME -c "CREATE EXTENSION postgis;"

You can also create a database in your GUI of choice (recommended: PGAdmin).

Ubuntu

Install postgres and required packages:

On Ubuntu 14.04

sudo apt-get install postgresql postgresql-contrib-9.3 postgresql-9.3-postgis-2.1

On Ubuntu 16.04

sudo apt-get install postgresql postgresql-contrib postgis

Create the database and a new postgres user with the following commands (replace <DB_NAME>, <DB_USER> and <DB_PASS> with your database name, user and password):

DB_USER=<DB_USER>
DB_PASS=<DB_PASS>
DB_NAME=<DB_NAME>
sudo -u postgres psql -c "CREATE USER $DB_USER WITH PASSWORD '$DB_PASS';"
sudo -u postgres psql -c "CREATE DATABASE $DB_NAME WITH OWNER $DB_USER;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE $DB_NAME TO $DB_USER;"
sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION postgis;"
sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION postgis_topology;"
sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION fuzzystrmatch;"
sudo -u postgres psql -d $DB_NAME -c "CREATE EXTENSION postgis_tiger_geocoder;"

Creating a Virtualenv

It’s best practice to make a virtual environment for your site. Make a folder to hold your virtual environment and cd into it. This can go anywhere but avoid /var/www or anywhere inside your tendenci site directory.

sudo mkdir /srv/tendenci/ cd /srv/tendenci/

Make a virtual environment called ‘venv’ and activate it.

sudo virtualenv venv source venv/bin/activate

Creating a new tendenci project

Make sure Django 1.8 is installed in your environment (sudo is not required if run in a virtualenv).

sudo pip install "Django>=1.8,<1.9"

In your environment, start a new tendenci project with the template (replace <project_name> with your project name) This download and install step will take some time and download around 70MB of packages.

 cd /var/www
sudo django-admin.py startproject --template=https://github.com/tendenci/tendenci-project-template/archive/master.zip <project_name>

Installing the requirements

Install the requirements with the following commands (sudo is not required if run in a virtualenv).

cd <project_name>
sudo pip install -r requirements/dev.txt

Next update the conf/local_settings.py file in the site folder (/var/www/<project_name>). Replace <DB_NAME>, <DB_USER> and <DB_PASS> for the setting DATABASE with the newly created database name, user and password.

Update your database name, database user and database password for the DATABASES setting in the conf/local_settings.py.

Setting up SECRET_KEY and SITE_SETTINGS_KEY

SECRET_KEY and SITE_SETTINGS_KEY are random strings 32 characters in length. You can update them manually in conf/local_settings.py or automatically update them with the following script.

cd /var/www/<project_name>/
curl https://gist.githubusercontent.com/jennyq/45de71a93cff774c593d/raw/30ede14eb133de66cc839cc0458a1e915368534e/setup_keys.sh | bash

Setting up the site

Now, use the deploy script to create the database tables and static media.

python manage.py migrate
python deploy.py

Load some defaults to ensure proper functioning

python manage.py load_creative_defaults

Make sure the execute permission is removed from the media/ directory

chmod -R -x+X media

To create an adminstrator login, run the following command and fill in the prompts:

python manage.py createsuperuser

Finally, we can use the runserver command so that we can view the site in our browser:

python manage.py runserver

Open http://127.0.0.1:8000/ in your browser to see your tendenci site!

Theming Options

Optional: If you want to use a different theme, you can set that theme with the following command, replacing my-theme-name with the name of your theme:

python manage.py set_theme my-theme-name

Scalable Installation

With a working test setup you can upgrade it to a fully functional, scalable install.

All of the commands below should be run on the command line after you are connected to the server and build on the work done in the previous sections.

Extra packages

You can install all of the necessary Ubuntu packages with the following commands:

sudo apt-get install openssh-server memcached libmemcached-dev nginx

This will install openssh-server to allow remote connections to the server along with memcache (a caching system) and nginx the web server.

Permissions

To change Tendenci to run as www-data (dropping root priviledges and increasing security) change permissions on the data directory (the Upstart and Systemd configuration provided below already runs tendenci as www-data)

sudo chown -R www-data: /var/www/<project_name>

Setting up Upstart

On Ubuntu, the Upstart functionality can be used to add the site as a service.

First, create a file at the path /etc/init/tendenci.conf.

cd /etc/init/
sudo touch tendenci.conf

The contents of that file should match the example below:

description "Tendenci Upstart Script"
start on runlevel [2345]
stop on runlevel [06]
respawn
respawn limit 10 5
setuid www-data
setgid www-data
script
    cd /var/www/<project_name>
    # if use virtualenv, uncomment the next line and replace <path-to-virtualenv> with your virtualenv path
    #. /<path-to-virtualenv>/bin/activate
    exec /srv/tendenci/venv/bin/gunicorn -w 2 -b 127.0.0.1:8000 conf.wsgi --max-requests 350
end script

You will need to replace the /var/www/<project_name> with the location of the site.

To start this service, use the following command:

sudo service tendenci start

If any changes in the future are made to the file conf/local_settings.py, the service should be restarted with this command:

sudo service tendenci restart

Setting up SystemD

On most distributions (Including recent Ubuntu systems) Systemd is the default init system.

Systemd Unit files should be created in /etc/systemd/system/ with a name of your choice (eg tendenci-test.service ). The contents of your unit file should look like this

[Unit]
Description=Start Tendenci instance
Requires=nginx.service postgresql.service
Wants=memcached.service
Before=nginx.service
After=postgresql.service

[Service]
WorkingDirectory=/var/www/<project_name>
PIDFile=/run/<project_name>.pid
Type=forking
KillMode=process
Restart=restart-always
ExecStart=/srv/tendenci/venv/bin/gunicorn              \
          --group www-data                             \
          --user www-data                              \
          --workers 4                                  \
          --bind=127.0.0.1:8000                        \
          --pid=/run/<project_name>.pid                \
          --pythonpath=/var/www/<project_name>         \
          --error-logfile=/var/log/<project_name>.error \
          --daemon                                     \
         conf.wsgi

[Install]
WantedBy=multi-user.target

To start the service run

systemctl start tendenci-test

and to enable it so it starts on boot use

systemctl enable tendenci-test

Setting up nginx

First, make an nginx configuration file for the site. This will be created at /etc/nginx/sites-available/<project_name> and should match the example below:

server {
    listen 80;
    server_name localhost;

    charset   utf-8;
    keepalive_timeout  65;
    client_max_body_size  30M;
    root /var/www/<project_name>/;

    location /static/ {
        access_log off;
        expires 30d;
    }

    location /media/ {
        access_log off;
        expires 30d;
    }

    location ~ /themes/([a-zA-Z0-9\-\_]+)/media/ {
        access_log off;
    }

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:8000/;
    }
}

Again, replace /var/www/<project_name>/ with the real path. If you have a domain name like example.com pointed at the server, add it to the server_name line in the place of localhost.

Next, create a symlink to the new file at /etc/nginx/sites-enabled/<project_name> with this command:

ln -s /etc/nginx/sites-available/<project_name> /etc/nginx/sites-enabled/<project_name>

Remove the default record from the sites-enabled with this command:

rm /etc/nginx/sites-enabled/default

Finally, restart the nginx service:

sudo service nginx restart

Setup Mail

For a mail server, install postfix. This package has 3 steps that you must respond to in order to complete the installation. If the server is alreadly configured with a domain name, enter that domain in the prompts. Otherwise, leave the defaults in place. To install the package, run this command:

apt-get install postfix

Memcached

Memcache is a service that can be used to speed up access to web pages by caching them in the systems memory for future use. Because tendenci is set up to use memcache by default, all that is required to enable it is installing it.

if you wish you increase the amount of memory memcache uses edit /etc/memcached.conf and change the ‘-m’ value from 64 to your desired cache size.

Load the site

The site should now be viewable, either at the ip address of the server, or at the domain name that has been setup.

Set up Cron Jobs for Production Sites

For production sites, you’ll need to set up cron jobs for the two management commands. The run_nightly_commands is to handle the tasks like membership notices, event reminders and other clean up jobs. The process_unindexed command is to process unindexed items in the queue.

30 2 * * * /usr/bin/python /path/to/tendenci/site/manage.py run_nightly_commands
*/60 * * * * /usr/bin/python /path/to/tendenci/site/manage.py process_unindexed

If you are using virtualenv, use the python executable from your site’s virtualenv.

30 2 * * * /path/to/virtualenv/bin/python /path/to/tendenci/site/manage.py run_nightly_commands
*/60 * * * * /path/to/virtualenv/bin/python /path/to/tendenci/site/manage.py process_unindexed

Running Multiple sites on one server

The process outlined above to install Tendenci can be used multiple times on a single server.

The steps to install Server Packages and the steps to replace the main postgres password do not need to be repeated.

When installing any additional Tendenci sites, replace the <project_name> used throughout the examples with a unique name.

When creating the database for any additional sites, be sure to use a unique database name and username. In the instructions above, the database name and username were both tendenci. Change this to something unique for each site.

Each additional Tendenci site will need to run on a different port internally. In the instructions, port 8000 was used. This will be changed for additional sites in the nginx configuration file as well as the .upstart.sh file for each new site.

You should also consider running a separate memcache instance for each tendenci install. This will increase the dedicated cache vailable for each instance and improve site performance.