.. _admin-guide:

Installation & Deployment
=========================

System Requirements
-------------------

The USO system runs in a Docker/Podman container environment, which simplifies deployment and management. Therefore,
the only requirement is a compatible Docker or Podman installation on your server. The software does not use
any privileged features of the host operating system and can therefore be run as a non-root user.

The following software is required to run the USO system:
* **Docker** or **Podman**: Containerization platform for running the USO instance.
* **Docker Compose**: Tool for defining and running multi-container Docker applications.
* **Buildah**: [Optional] Tool for building OCI and Docker container images.
* **Git**: Version control system to clone the USO repository.


Initial Setup
-------------
To create an initial instance of the USO system, follow these steps:

1. **Clone the Repository:**
   Use Git to clone the USO repository from GitHub::

    git clone https://github.com/michel4j/uso.git
    cd uso

2. **Create a Directory for storing persistent data:**
   This directory will hold the database and other persistent data. If you plan to use an external database,
   you still need to create this directory, since it will contain site-specific configuration and log files::

    mkdir -p /path/to/clsi-uso-instance

3. **Prepare the Instance:**
   Run the `prepare-instance.sh` script from within the uso top-level directory, to set up the initial
   configuration and create necessary sub-directories. This command will also detect your container
   environment (Docker or Podman), build an image for the USO application, and set up the `docker-compose.yml`
   file accordingly::

    ./deploy/prepare-instance.sh /path/to/clsi-uso-instance

   Once the script completes, you will have a subdirectory tree inside your provided directory similar to this::

    usonline/
    ├── database
    ├── docker-compose.yml
    ├── .env
    └── local
        ├── kickstart
        ├── logs
        ├── media
        │   └── css
        │       └── custom.css
        └── settings.py


   * The `database` directory will be used for the PostgreSQL database,
   * The `local` directory contains site-specific configuration files and directories:
   * `kickstart`: Contains initial data to be loaded into the system. Place your initial data files here.
   * `logs`: Directory will be used for storing log files.
   * `media`: Directory for media files, content uploaded by users, will be stored here.
   * `css/custom.css`: Custom CSS file for styling the USO instance. You can edit this file to apply your own styles
     and override build-inn styles.
   * `settings.py`: Local settings file for the USO instance. Edit this file to override default settings
     and configure your instance. If you need to use an external database, the database settings should be set here.
     Additionally you can configure email settings, administrator email addresses, API keys, and custom user
     profile managers. See the :ref:`Configuration <admin-configuration>` section for more details.
   * `.env`: Environment variables file for the storing secrets. This file is automatically generated by the setup script
     and contains sensitive information such as database passwords, secret keys, etc. Edit this file to set your own
     secrets.
   * The `docker-compose.yml` file contains the container configuration for running the USO instance.
     for running the USO instance in a Docker container. You can edit this file to customize the container settings,
     such as environment variables, ports, and volumes.

4. **Start the USO Instance:**
   Navigate to the directory where you created the instance and run the following command to start the USO instance::

    cd /path/to/clsi-uso-instance/usonline
    docker compose up -d

   or if you are using Podman::

    podman-compose up -d

   This command will start the USO application in detached mode. You can check the logs using any of the following::

    docker-compose logs -f

    podman-compose logs -f

4. **Access the USO Instance:**
   Once the containers are running, you can access the USO instance in your web browser at: http://localhost:8080
   If you are running the instance on a remote server, replace `localhost` with the server's IP address or hostname.
   Check the contents of the `.env` file for login credentials for the admin account.