View on GitHub


Test Coverage
.. _install-docker:

Installing Locally using Docker

.. admonition:: Is this the best install method for you?
  :class: attention

  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`

.. attention:: If you need an offline copy of Tabbycat, installing using Docker should be simpler and quicker than using the "Install Locally on…" instructions for your operating system. However if a Docker installation doesn't work as outlined below, it's harder to address what isn't working. If you encounter any problems with Docker, we recommend using the "Install Locally on…" option as a fallback, but if you need to do so, `please also report the issue you're having on GitHub <,%20and%20please%20be%20as%20specific%20as%20you%20can%20about%20the%20problem%20you%20encountered%3A%0D%0D>`_ or :ref:`contact the developers <authors>`.

Docker is an application that makes it very easy to load and run a specific collection of software. It allows us to bundle everything necessary to run Tabbycat into a single package rather than have users install everything needed step-by-step. Once set up, Docker will allow you to start and stop a webserver (that in turn runs Tabbycat) on your computer whenever you want and without the need for internet access.

1. Download Tabbycat

1. `Go to the page for our latest release <>`_.

2. Download the zip or tar.gz file.

3. Extract all files in it to a folder of your choice.

2. Install Docker

Install **Docker Desktop** for your operating system from the `Docker website <>`_.

Notes for specific operating systems:

- **Windows users** will be asked to enable Hyper-V Windows Features or WSL 2 Features while installing Docker. Please do so and restart as asked. If you encounter any problems, our documentation might be outdated—check Docker's documentation `for Windows 10 Pro/Enterprise/Education <>`_ or `for Windows 10 Home <>`_.
- **Linux users** will be directed to install `Docker Engine <>`_ instead.

3. Run Tabbycat in Docker

.. rst-class:: spaced-list

1. Ensure that Docker application is open (there should be a whale icon in your menu/task bar) and that it says that Docker is running.

2. Browse to the location where you extracted Tabbycat to. Open up the **bin** folder there. Within that folder:

    - If you're on macOS, press the Control key, click the icon for **osx_docker_start.command**, then choose Open from the shortcut menu.
    - If you're on Windows, open **windows_docker_start.bat**.
    - If you're on Linux, open up a terminal in the Tabbycat folder (*i.e.* the folder containing ````) and run ``docker-compose up``.

3. A terminal window should pop up and lots of text should scroll by. If this is your first time running Docker, it may take a while (30 minutes or more) to download the virtual machine. The last few lines will say something like:

  .. code-block:: none

    web_1  | Django version 2.2.13, using settings 'settings'
    web_1  | Starting ASGI/Channels version 2.2.0 development server at
    web_1  | Quit the server with CONTROL-C.

4. Open up http://localhost:8000/ (Windows) or (macOS/Linux) in a browser of your choice!

.. note:: If you want to reopen Tabbycat at a later time (say after restarting), just repeat the steps in this section.