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:

Clone the Repository: Use Git to clone the USO repository from GitHub:
```
git clone https://github.com/michel4j/uso.git
cd uso
```
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
```
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:
```
./deploy/prepare-instance.sh /path/to/clsi-uso-instance [nginx|apache|devel]
```
If not specified, the script will default to apache as the web server. The devel option is intended for setting up a development environment, and will bind the database and cache containers to the host ports. The nginx option will set up the instance to use Nginx as the web server. The apache option will set up the instance to use Apache as the web server. Currently, the apache option has been tested more thoroughly but the nginx provides the best performance.

Once the script completes, you will have a subdirectory tree inside your provided directory similar to this:
```
uso-apache/
├── 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 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 and to update other system environment variables.
- The docker-compose.yml file contains the container configuration 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.
Build the image:
```
./deploy/build-image.sh [nginx|apache]
```
This command will detect your container environment (Docker or Podman), build an image for the USO application for the selected server (nginx or apache), and tag it as usonline:nginx or usonline:apache.
[OPTIONAL] Generate fake test data: If you want to generate some fake test data for your USO instance, you can run the following commands before starting the instance. NOTE: Fake data generated after the instance has started will not be loaded automatically. This python script needs external dependencies which are listed in the ./deploy/requirements.txt file. Therefore, you need to install the dependencies first, or run the command from your fully setup development environment:
```
./deploy/generate-data.py /path/to/instance/uso-apache/local
```
This will create fake data in the local/kickstart directory, and also generate fake user profile images in the local/media directory. Pay close attention to the printed log messages as the common password for all generated users is also printed. You force a specific password as follows:
```
DJANGO_PASSWORD=CustomPassword ./deploy/generate-data.py /path/to/instance/uso-apache/local
```
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/instance/uso-apache
docker compose up -d
```
or if you are using Podman:
```
podman-compose up -d
```
This command will start the USO application in detached mode. Note, if using fake data, the first time the application runs, it may take several minutes to load all the data. You can check the logs using any of the following:
```
docker-compose logs -f

podman-compose logs -f
```
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 /path/to/instance/uso-apache/.env and update the server name, port, etc. Login credentials for the admin account are also oavailable in this file.