Getting started

First off, you need Python 3.5 or above and Redis (the Windows port works, too, just make sure you run redis-server.exe as Administrator). After you installed the requirements (if necessary), start a terminal session (cmd.exe on Windows) and install virtualenv (using a virtualenv is required):

pip3 install virtualenv

Once you have that, create a virtual environment as follows:

virtualenv path/to/where/you/want/to/create/your/virtualenv

Any path will do; I'd suggest /dwarfenv. After you've created the virtualenv, you'll need to enter/activate it. On Linux, that would be:

source /dwarfenv/bin/activate

And on Windows:

/dwarfenv/Scripts/activate.bat`

(Replace /dwarfenv with the path to your virtual environment.) You should now see the name of your virtualenv in brackets (e.g. (dwarfenv)). If you do, you can now start installing the requirements:

pip install django redis django-redis-cache djangorestframework psycopg2 "git+https://github.com/Rapptz/discord.py@rewrite"
pip install aioredis --no-deps

If you're on Linux or have Microsoft Visual Studio installed on your Windows system, install the hiredis Redis parser as well to speed up access to the Redis database:

pip install hiredis

After you've done that, start a new Django project in a directory of your choice as follows:

django-admin startproject project-name

(Replace project-name with the name of your project, e.g. dwarfproject. Do NOT name it dwarf, though.) This will create the folder structure of your Django project. Now you can download Dwarf by going to your project directory (cd project-name) and issueing the following (use Git Bash for this if you're on Windows):

git clone https://github.com/Dwarf-Community/dwarf
cd dwarf
git clone https://github.com/Dwarf-Community/Dwarf-Extensions extensions

You now need to adjust the settings.py file (in /project-name/project-name) as follows:

• Set the database backend to PostgreSQL (recommended): Example:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'databasename',
        'USER': 'someuser',
        'PASSWORD': 'S3kr1t!',
        'HOST': 'localhost',
        'PORT': '5432',
        'CONN_MAX_AGE': 30,  # in seconds
    }
}

• Add Dwarf (dwarf.apps.DwarfConfig) and the REST framework (rest_framework) to your installed apps: Example:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',  # this adds the REST framework
    'dwarf.apps.DwarfConfig',  # this adds Dwarf
]

• Register Dwarf's user model as the user model used for authentication:

AUTH_USER_MODEL = 'dwarf.User'

• You also have to add your Redis credentials to settings.py (Redis is currently the only cache backend available for Dwarf):

DWARF_CACHE_BACKEND = {
    'redis': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': 'S3kr1t!',
        'DB': 0,
    }
}

Now that you've done that, you need to decide at which URL you want to make Dwarf's web frontend available. Open /project-name/project-name/urls.py and make it look something like this:

from django.conf.urls import url, include
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^dwarf/', include('dwarf.urls')),
]

Take a closer look at r'^dwarf/'. That is a so-called regular expression that defines where Dwarf should be made accessible. If you want to host Dwarf at discord/, your urlpatterns would look like this:

from django.conf.urls import url, include
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^discord/', include('dwarf.urls')),
]

If you want to host it at the root, your urlpatterns would look as follows:

from django.conf.urls import url, include
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^', include('dwarf.urls')),
]

Keep in mind that Django checks these urlpatterns from top to bottom, so if you'd put the second urlpattern above the first in the above example, you wouldn't be able to access anything via the web interface but Dwarf.

Finally, you have to let Django setup the database for you:

python manage.py makemigrations
python manage.py makemigrations dwarf
python manage.py migrate

That should be it for now. There will be more things to install as soon as the web front-end part will be released, such as nginx and gunicorn, so keep an eye at our Discord server.

You can start the bot by going to your Django project's directory and issueing the following command (after you activated your virtualenv as described above): python manage.py startbot

Have fun! If you need help, drop by the Discord server and we'll try to help you.