Is this the best installation method for you?
In most cases, we recommend doing an :ref:`internet-based installation on Heroku <install-heroku>` instead. If you decide to do a local installation, be sure to read our page on :ref:`local installations <install-local>` to help you understand what's going on, particularly this section: :ref:`install-decision`
If you just want to quickly set up a copy of Tabbycat to run locally on Linux, consider :ref:`installing using Docker<install-docker>`, which is a shorter process than the one below.
The instructions apply to both Linux, and :ref:`Linux on Windows <install-wsl>`.
You need to be familiar with command-line interfaces to get through this comfortably. While a background in the specific tools Tabbycat uses (Python, PostgreSQL, etc.) will make things easier, it's not necessary: we'll talk you through the rest.
Advanced users
If you wish to use an SQL engine other that PostgreSQL, most of Tabbycat should work, but a few features rely on SQL functions that aren't supported by all engines. To configure Tabbycat to use a different engine, set the DATABASES
Django setting accordingly.
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash - # add Node.js source repository sudo apt install python3-dev python3-venv postgresql libpq-dev nodejs gcc g++ make git clone https://github.com/TabbycatDebate/tabbycat.git cd tabbycat git checkout master sudo -u postgres createuser myusername --createdb --pwprompt # skip if not first time createdb mydatabasename
Then create settings/local.py as described :ref:`below <local-settings-linux>`, then:
python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r ./config/requirements_core.txt npm install cd tabbycat dj migrate npm run build dj collectstatic dj createsuperuser dj runserver
First, you need to install all of the software on which Tabbycat depends, if you don't already have it installed.
Advanced users
These instructions are for Ubuntu, and are targeted at Ubuntu 18.04. If you have another distribution of Linux, we trust you'll know how to navigate the package manager for your distribution to install the dependencies.
Tabbycat requires Python 3.6 or later. You probably already have Python 3, but you'll also need the development package in order to install Psycopg2 later. The venv
module will come in handy too. Install:
$ sudo apt install python3-dev python3-venv
Check the version:
$ python3 --version Python 3.6.2
Warning
Tabbycat does not support Python 2. You must use Python 3.6 or later.
PostgreSQL is a database management system.
Install PostgreSQL using the PostgreSQL installation instructions here.
Normally, installing the latest stable version should be best, but if you're having issues, install the same version as the current default version on Heroku, as that will be what is currently most commonly used with Tabbycat. If you're planning on pushing data between your local installation and a Heroku site, it's best to match the Heroku's current default version.
You'll also need the libpq-dev
package in order to install Psycopg2 later:
$ sudo apt install libpq-dev
Node.js is a JavaScript runtime.
Tabbycat requires Node and its package manager to compile front-end dependencies. Install using:
$ sudo apt install curl $ curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash - $ sudo apt install -y nodejs $ sudo ln -s /usr/bin/nodejs /usr/bin/node
Some of the Python packages require GCC, G++ and Make in order to install:
$ sudo apt install gcc g++ make
Choose either of the following two methods.
If you have Git, life will be easier if you clone `our GitHub repository`_:
$ git clone https://github.com/TabbycatDebate/tabbycat.git $ git checkout master
(You can find out if you have Git using git --version
. If you don't, you can install it using sudo apt install git
.)
Note
The default branch is develop
, so you need to explicitly change the branch to master
, which is what the git checkout master
line does.
Advanced users
You might like to fork the repository first, to give yourself a little more freedom to make code changes on the fly (and potentially :ref:`contribute <contributing>` them to the project).
If you don't want to use Git, simply download and extract:
$ wget https://github.com/TabbycatDebate/tabbycat/archive/|vrelease|.tar.gz $ tar xf |vrelease|.tar.gz $ cd tabbycat-|release|
Hint
You can skip step 1 if this is not your first installation. Every Tabbycat installation requires its own database, but they can use the same login role if you like.
- Create a new user account with a password, replacing
myusername
with whatever name you prefer. If you don't know what username to pick, usetabbycat
. Grant this user the ability to create databases, since this'll make it easier to spin up new instances of Tabbycat in the future.
$ sudo -u postgres createuser myusername --createdb --pwpromptTip
If you'll be running multiple instances of Tabbycat, developing, or diving into the database yourself, you might find it convenient to set up client authentication so that you don't need to do all manual operations from
sudo -u postgres
. See the PostgreSQL documentation on client authentication for more information. For example, you could add alocal all myusername md5
line to the pg_hba.conf file, or you could define a mapping in pg_ident.conf and append themap=
option to thelocal all all peer
line in pg_hba.conf.
Create a new database, replacing
mydatabasename
with whatever name you prefer, probably the name of the tournament you're running:$ createdb mydatabasename
Almost there!
Navigate to your Tabbycat directory:
$ cd path/to/my/tabbycat/directory
- Start a new virtual environment. We suggest the name
venv
, though it can be any name you like:
$ python3 -m venv venv
Run the
activate
script. This puts you "into" the virtual environment:$ source venv/bin/activate
Install Tabbycat's requirements into your virtual environment:
$ pip install --upgrade pip $ pip install -r ./config/requirements_core.txt $ npm install
Navigate to the tabbycat/settings sub folder and copy local.example to local.py. Find this part in your new local.py, and fill in the blanks as indicated:
DATABASES = { 'default': { 'ENGINE' : 'django.db.backends.postgresql', 'NAME' : '', # put your PostgreSQL database's name in here 'USER' : '', # put your PostgreSQL login role's user name in here 'PASSWORD': '', # put your PostgreSQL login role's password in here 'HOST': 'localhost', 'PORT': '5432', } }Optionally, replace the value in this line in the same file with your own time zone, as defined in the IANA time zone database (e.g.,
Pacific/Auckland
,America/Mexico_City
,Asia/Kuala_Lumpur
):TIME_ZONE = 'Australia/Melbourne'
Navigate to the tabbycat sub-directory, initialize the database, compile the assets, and create a user account for yourself:
$ cd tabbycat $ dj migrate $ npm run build $ dj collectstatic $ dj createsuperuser
Start Tabbycat!
$ dj runserverIt should show something like this:
serving on http://127.0.0.1:8000
- Open your browser and go to the URL printed above. (In the above example, it's http://127.0.0.1:8000.) It should look something like the screenshot below. If it does, great! You've successfully installed Tabbycat.
Naturally, your database is currently empty, so proceed to :ref:`importing initial data <importing-initial-data>`.
To start your Tabbycat instance up again next time you use your computer:
$ cd path/to/my/tabbycat/directory $ source venv/bin/activate $ dj runserver