tutor/docs/local.rst

.. _local:

Local deployment
================

This method is for deploying Open edX locally on a single server. Docker images are orchestrated with `docker-compose <https://docs.docker.com/compose/overview/>`_.

The following commands should be run inside the ``deploy/local`` folder::

    cd deploy/local

You can use these commands individually instead of running the full installation with ``make all``.

Configuration
-------------

::

    make configure

This is the only non-automatic step in the install process. You will be asked various questions about your Open edX platform and appropriate configuration files will be generated. If you would like to automate this step then you should run ``make configure`` interactively once. After that, you will have a ``config.json`` file at the root of the repository.

If you want to run a fully automated install, upload the ``config.json`` file to wherever you want to run Open edX, and then run ``make configure SILENT=1`` instead of ``make configure``. All values from ``config.json`` will be automatically loaded.

Downloading docker images
-------------------------

::

    make update

You will need to download the docker images from `Docker Hub <https://hub.docker.com/r/regis/openedx/>`_. Depending on your bandwidth, this might take a long time. Minor image updates will be incremental, and thus much faster.

Database management
-------------------

::

    make databases

This command should be run just once. It will create the required databases tables and apply database migrations for all applications.


If migrations are stopped with a ``Killed`` message, this certainly means the docker containers don't have enough RAM. See the :ref:`troubleshooting` section.

Running Open edX
----------------

::

    make run

This will launch the various docker containers required for your Open edX platform. The LMS and the Studio will then be reachable at the domain name you specified during the configuration step. You can also access them at http://localhost and http://studio.localhost.

To stop the running containers, just hit Ctrl+C.

In production, you will probably want to daemonize the services. Instead of ``make run``, run::

    make daemonize

And then, to stop all services::

    make stop

Creating a new user with staff and admin rights
-----------------------------------------------

You will most certainly need to create a user to administer the platform. Just run::

    make staff-user USERNAME=yourusername EMAIL=user@email.com

You will asked to set the user password interactively.

Importing the demo course
-------------------------

On a fresh install, your platform will not have a single course. To import the `Open edX demo course <https://github.com/edx/edx-demo-course>`_, run::

    make demo-course

Updating the course search index
--------------------------------

The course search index can be updated with::

    make reindex-courses

Run this command periodically to ensure that course search results are always up-to-date.

.. _portainer:

Docker container web UI with `Portainer <https://portainer.io/>`_
-----------------------------------------------------------------

Portainer is a web UI for managing docker containers. It lets you view your entire Open edX platform at a glace. Try it! It's really cool::

    make portainer

.. .. image:: https://portainer.io/images/screenshots/portainer.gif
    ..:alt: Portainer demo

After launching your platfom, the web UI will be available at `http://localhost:9000 <http://localhost:9000>`_. You will be asked to define a password for the admin user. Then, select a "Local environment" to work on and hit "Connect" and select the "local" group to view all running containers.

Among many other things, you'll be able to view the logs for each container, which is really useful.

Loading different production settings for ``edx-platform``
----------------------------------------------------------

The default settings module loaded by ``edx-platform`` is ``tutor.production``. The folders ``tutor/deploy/env/openedx/settings/lms`` and ``tutor/deploy/env/openedx/settings/cms`` are mounted as ``edx-platform/lms/envs/tutor`` and ``edx-platform/cms/envs/tutor`` inside the docker containers. Thus, to use your own settings, you must do two things:

1. Copy your settings files for the lms and the cms to ``tutor/deploy/env/openedx/settings/lms/mysettings.py`` and ``tutor/deploy/env/openedx/settings/cms/mysettings.py``.
2. Load your settings by adding ``EDX_PLATFORM_SETTINGS=tutor.mysettings`` to ``tutor/deploy/local/.env``.

Of course, your settings should be compatible with the docker install. You can get some inspiration from the ``production.py`` settings modules generated by Tutor.

Additional commands
-------------------

All available commands can be listed by running::

    make help

How to upgrade from `openedx-docker`
------------------------------------

Before this project was renamed to Tutor, it was called "openedx-docker", and many additional changes were introduced at the same time. If you checked out openedx-docker before the rename, you can upgrade by running the following commands::

    make stop               # Stop all services
    git pull                # Upgrade to the latest version of Tutor
    make upgrade-to-tutor   # Move some configuration files
    make local              # Re-configure and restart the platform