Install guides

These instructions are for a production installation. For development installation instructions, see the Development pages.

If you have issues following these instructions, please contact us via Community.

Available guides:

Ubuntu (14.04, manual)

This guide is very opinionated and experienced sysadmins will most likely want to do things differently. This guide will give you a Socialhome production install on uWSGI using an Apache2 web server.

Supported versions

This guide is written for Ubuntu 14.04 (with Upstart). Guide for non-upstart Ubuntu versions coming soon!


Fix locales

Ubuntu 14.04 has a problem with locales which could bring problems when installing PostgreSQL. If you have already installed PostgreSQL, you can probably skip this step.

Check these two commands:

echo $LC_ALL

if both of them come out empty, edit the file /etc/default/locale and add the two following lines:


Save, logout and log back in.

See this post for example for a description of this problem.

Install system packages

# Generic packages needed
sudo apt-get install git python-virtualenv python3-setuptools python-dev python3-dev build-essential

# PostgreSQL dependencies
sudo apt-get install libpq-dev

# federation dependencies
sudo apt-get install libxml2-dev libxslt-dev lib32z1-dev

# Redis
sudo apt-get install redis-server

Install Node.js

Node.js version 6+ is needed for statics management. Install it by following the Node.js install guides.

Install PostgreSQL

If not installed or not using a remote PostgreSQL DB, install the database engine.

sudo apt-get install postgresql

Create a database and user. Note down password for later.

sudo su - postgres
createuser -P socialhome
createdb -O socialhome socialhome

Create a local user

It’s better to run applications under their own user.

sudo adduser socialhome --disabled-login
sudo chmod 750 /home/socialhome

# Add user group to www-data groups so we can protect users home folder
sudo adduser www-data socialhome

Set up uWSGI

# Create logs path
sudo -u socialhome mkdir /home/socialhome/logs

Create the ini file with /home/socialhome/uwsgi.ini and add the following contents to it.


Set up Apache

if not already installed, install the Apache2 web server.

sudo apt-get install apache2 libapache2-mod-proxy-uwsgi

Enable some necessary modules.

sudo a2enmod proxy_uwsgi
sudo a2enmod proxy_wstunnel
sudo a2enmod proxy
sudo a2enmod ssl

Add an Apache virtualhost file /etc/apache2/sites-available/socialhome.conf with the following content, replacing instances of yourdomain.tld with your real domain for your Socialhome instance:

<VirtualHost *:80>
    ServerName yourdomain.tld
    ServerAlias www.yourdomain.tld
    RedirectPermanent / https://yourdomain.tld/

<VirtualHost *:443>
    ServerName yourdomain.tld
    ServerAlias www.yourdomain.tld
    ServerAdmin webmaster@yourdomain.tld

    Alias /robots.txt /home/socialhome/socialhome/staticfiles/robots.txt
    Alias /favicon.ico /home/socialhome/socialhome/staticfiles/favicon.ico
    Alias /media /home/socialhome/socialhome/socialhome/media

    <Directory /home/socialhome/socialhome/socialhome/media>
        Require all granted
        Options -MultiViews -Indexes

    ProxyPass /media !
    ProxyPass /ch/ ws://
    ProxyPass / uwsgi://

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/yourdomain.tld/cert.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.tld/privkey.pem
    SSLCertificateChainFile /etc/letsencrypt/live/yourdomain.tld/chain.pem

Enable Apache virtualhost

sudo a2ensite socialhome

Get LetsEncrypt certificate

We wouldn’t want to run our site without HTTPS. Install Certbot and get an LetsEncrypt certificate.

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install python-certbot-apache

Launch Certbot and answer any questions to install the certificates.

certbot --apache certonly

Now you should be able to restart Apache.

sudo service apache2 restart

Change to Socialhome user

Change to user socialhome for the rest of the guide.

sudo su - socialhome

Install Virtualenvwrapper

This is the easiest way to manage Python virtualenvs. We also add production Django configuration reference at the same time.

pip install --user virtualenvwrapper

Add the following lines to your .bashrc and reload it via source ~/.bashrc.

export WORKON_HOME=$HOME/.virtualenvs
source ~/.local/bin/
export DJANGO_SETTINGS_MODULE=config.settings.production

Create Python virtualenv

mkvirtualenv -p /usr/bin/python3 socialhome

The virtualenv is automatically activated. When you need it in the future, just type workon socialhome.

Update pip and setuptools

pip install -U pip setuptools==30.4

Install pip-tools

pip-tools is a handy tool to keep environments clean and all dependencies nicely pinned.

pip install -U pip-tools

Get Socialhome code

git clone
cd socialhome

Install Python dependencies

We use the pip-tools command to ensure dependencies are at the correct versions.


Create configuration

Create the file env.local with the following contents, replacing values as needed.

You must change or add the following values:

  • Replace DATABASEPASSWORDHERE with the database password typed in earlier.
  • DJANGO_SECRET_KEY must be added. Generate one for example here.

For further configuration tips, see Running an instance.

Make the env file a bit less readable.

chmod 0600 env.local

Configure email sending

Note, email is required for signing up. Users will not be able to sign up if the instance does not have working email sending. See DJANGO_EMAIL_BACKEND on how to configure email sending.

Run migrations

python migrate

Install statics

npm install
node_modules/.bin/bower install
node_modules/.bin/grunt build
python collectstatic

If you want to try the new Vue.js frontend, also do:

npm run dev
python collectstatic

Search index

The search indexes must be initialized, otherwise there will be an error when trying to use search. Run this command once:

python rebuild_index

Any further changes to indexes objects will be maintained automatically from this point onwards. If you ever need to rebuild the index from scratch, use the same command.

Set the correct domain name in Django

Load up the Django shell with python shell_plus and then execute the following, replacing “yourdomain.tld” with your domain and “Socialhome” as the name of your site, assuming you want the name changed:

Site.objects.filter(id=1).update(domain="yourdomain.tld", name="Socialhome")

Set up Circus

Exit Socialhome user and create Upstart configuration for Circus process manager. Circus is used to control various processes that are needed in addition to the web server. This allows starting one process that will start and maintain a bunch of other processes we need. A configuration file for the processes is provided within the repository.

Create Upstart configuration /etc/init/socialhome.conf with the following content:

description "Socialhome"
start on runlevel [2345]
stop on runlevel [06]
setuid socialhome
setgid socialhome


env PYTHONPATH="/home/socialhome/socialhome"
env SOCIALHOME_HOME="/home/socialhome"
env VIRTUAL_ENV=/home/socialhome/.virtualenvs/socialhome
env LC_CTYPE=en_US.UTF-8
env LC_ALL=C.UTF-8
env LANG=C.UTF-8
env DJANGO_SETTINGS_MODULE=config.settings.production

chdir /home/socialhome/socialhome

exec /home/socialhome/.virtualenvs/socialhome/bin/circusd config/circus.ini

Start Circus. It will automatically start on system boot.

sudo service socialhome start


That wasn’t so hard was it?

Navigate to the domain you chose to install Socialhome on and hopefully you will see a landing page. Signups will be open. Unless you want to keep it that way, after creating your own account, you should close the signups to avoid random people signing up to your instance. See configuration tips at Running an instance.

If you didn’t configure emails, you cannot complete your user account registration without the email confirmation link. See Confirming user emails via the shell.

If you want to set your initially created user as admin, see Admin user.

Ubuntu (14.04, Ansible)

See this Ansible role.

Other platforms

PR’s welcome for guides for more platforms!