Skip to main content

Self-Hosting OpenUGC

If you want full control over your deployment, you can run OpenUGC locally on your own machine.
This guide walks you through installing the required tools, setting up environment variables, and running the API. On this guide we will show how to host it on Windows, but you can still use this as guide and do the equivalent for Linux or MacOS.

1. Install Prerequisites​

Before running OpenUGC locally, make sure you have the following installed:

  • Java 17 (required for Spring Boot)
  • Maven (for building and running the project)
  • Docker Desktop (optional, in case you prefere running it in a container)
  • Postman (optional, but recommended to test the API endpoints)

2. Clone the Repository​

Open a terminal and run:

git clone https://github.com/PauloWgDev/OpenUGC.git
cd OpenUGC

3. Configure Environment Variables​

OpenUGC uses environment variables for database, authentication, and storage configuration.

To make this easy, you can create a PowerShell or a Bash script like this:

PowerShell - run.ps1​

Save the following as run.ps1 in your project root and modify the values with your own ones:

# Automatically set all the environment variables and run the project

# Database Profile
$env:DATABASE_PROFILE = "postgres"

# Local PostgreSQL Database Configuration
$env:DATABASE_URL = "jdbc:postgresql://localhost:5433/openugc"
$env:DATABASE_USERNAME = "postgres"
$env:DATABASE_PASSWORD = "secretpassword"

# JWT Secret for local auth
$env:JWT_SECRET = "aSecureRandomGeneratedKeyThatIsAtLeast32BytesLong!"

# Storage Type
$env:STORAGE_TYPE = "local"

# Local Storage Settings
$env:STORAGE_LOCATION = "F:/UGC_Storage"
$env:STORAGE_BASEURL = "http://localhost:8080/storage/"

# Cloud Storage Settings
$env:CLOUD_BUCKET = "u3gc-uploads"
$env:CLOUD_BASEURL = "https://storage.googleapis.com/open-uploads/"

# Google
$env:GOOGLE_APPLICATION_CREDENTIALS = "F:/Path/To/Credentials/arched-sorter-459106-f6-be936d47ab6a.json"

# Run Project
mvn spring-boot:run

How to Run it:​

  1. Open PowerShell in your project root.

  2. Run the script:

.\run.ps1
  1. The script will set all environment variables and start the project automatically.

Bash - run.sh​

Save the following as run.sh in your project root and modify the values with your own ones:

#!/bin/bash
# Automatically set all the environment variables and run the project

# Database Profile
export DATABASE_PROFILE="postgres"

# Local PostgreSQL Database Configuration
export DATABASE_URL="jdbc:postgresql://localhost:5433/openugc"
export DATABASE_USERNAME="postgres"
export DATABASE_PASSWORD="secretpassword"

# JWT Secret for local auth
export JWT_SECRET="aSecureRandomGeneratedKeyThatIsAtLeast32BytesLong!"

# Storage Type
export STORAGE_TYPE="local"

# Local Storage Settings
export STORAGE_LOCATION="/home/your_user/UGC_Storage"
export STORAGE_BASEURL="http://localhost:8080/storage/"

# Cloud Storage Settings
export CLOUD_BUCKET="u3gc-uploads"
export CLOUD_BASEURL="https://storage.googleapis.com/open-uploads/"

# Google credentials
export GOOGLE_APPLICATION_CREDENTIALS="/home/paulo/Path/To/Credentials/arched-sorter-459106-f6-be936d47ab6a.json"

# Run Project
mvn spring-boot:run

How to Run it:​

  1. Give it execute permissions:
chmod +x run.sh
  1. Run it:
./run.sh
  1. The script will set all environment variables and start the project automatically.

4. Verify the API is Running​

Once the project compiles and runs, the API should be available at:

http://localhost:8080/api

5. Testing with Postman​

Before connecting to your game engine, it’s a good idea to test endpoints with Postman.

Register a User​

Method: POST

URL: http://localhost:8080/api/auth/register

Body (JSON):

{
  "username": "testuser",
  "credential": "mypassword",
}

If successful, you’ll get back a success message.

Login​

Method: POST

URL: http://localhost:8080/api/auth/login

Body (JSON):

{
  "username": "testuser",
  "credential": "mypassword"
}

Response will include a JWT token you can use for authenticated requests.

Test Authenticated Endpoints​

Method: GET

URL: http://localhost:8080/api/content?page=0&size=5

Headers:

Authorization: Bearer <your-jwt-token>

cURL example:

curl -X GET "http://localhost:8080/api/content?page=0&size=5" \
  -H "Authorization: Bearer <your-jwt-token>"

Returns a paginated list of content, e.g.:

{
  "content": [],
  "pageable": { "pageNumber": 0, "pageSize": 5 },
  "totalElements": 0
}

If your received a response similar to the above, congratulations you have successfully self-hosted OpenUGC and you are ready to start setting up you UGC on Unity or any other Game Engine!!!