Getting Started

1. Prerequisites

Before you start, make sure the following are installed and available on your system:

Verify your Java version:

java --version
# Should print something like: openjdk 21.0.3 2024-04-16

2. Clone the repository

Clone Open Task Hub from GitHub and enter the project directory:

git clone https://github.com/robertvokac/open-task-hub
cd open-task-hub

The Gradle wrapper (gradlew) is included — no separate Gradle installation is needed.

3. Create the database

Open Task Hub needs a PostgreSQL database. Connect to PostgreSQL as a superuser and run the following SQL:

CREATE USER forge WITH PASSWORD 'forge';
CREATE DATABASE open_task_hub OWNER forge;
GRANT ALL PRIVILEGES ON DATABASE open_task_hub TO forge;

If you prefer Docker, start PostgreSQL with a single command:

docker run -d --name oth-db \
  -e POSTGRES_DB=open_task_hub \
  -e POSTGRES_USER=forge \
  -e POSTGRES_PASSWORD=forge \
  -p 5432:5432 \
  postgres:16

Flyway will automatically apply all database migrations on first startup — no manual schema creation needed beyond the empty database.

4. Configure the application

The application reads its configuration from environment variables or from src/main/resources/application.yml. The defaults match the database created in the previous step.

To override defaults, set environment variables before running:

export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/open_task_hub
export SPRING_DATASOURCE_USERNAME=forge
export SPRING_DATASOURCE_PASSWORD=forge
export SERVER_PORT=8080
export OPEN_TASK_HUB_BOOTSTRAP_ADMIN_PASSWORD=admin123
export OPEN_TASK_HUB_BOOTSTRAP_USER_PASSWORD=robert123

Alternatively, edit src/main/resources/application.yml directly for a local development setup:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/open_task_hub
    username: forge
    password: forge
server:
  port: 8080
open-task-hub:
  bootstrap:
    admin-password: admin123
    user-password:  robert123

See the full configuration reference for all available options.

5. Run the application

Start Open Task Hub using the Gradle wrapper:

./gradlew bootRun

On Windows use:

gradlew.bat bootRun

You should see Spring Boot startup logs ending with something like:

...
Started OpenTaskHubApplication in 3.412 seconds (process running for 3.7)
Open Task Hub is ready at http://localhost:8080

To build a runnable JAR instead:

./gradlew bootJar
java -jar build/libs/open-task-hub-*.jar

6. Log in

Open your browser and navigate to:

http://localhost:8080

You will be redirected to the login page at /login. Use the bootstrap credentials:

After login, you will land on the dashboard at /dashboard.

7. Create your first project

You can create a project from the web UI or via the API.

Via the web UI

1. Click New Project on the dashboard.
2. Fill in a short Key (e.g. MYAPP), a Name and optional Description.
3. Choose visibility: PUBLIC or PRIVATE.
4. Click Create Project.

Via the REST API

curl -u admin:admin123 \
  -X POST http://localhost:8080/api/projects \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "MYAPP",
    "name": "My Application",
    "description": "Main product backlog",
    "visibility": "PRIVATE"
  }'

8. Create your first issue

Navigate to your new project and click New Issue, or use the API:

curl -u admin:admin123 \
  -X POST http://localhost:8080/api/projects/MYAPP/issues \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My first issue",
    "description": "This is the first issue in the project.",
    "type": "TASK",
    "priority": "NORMAL"
  }'

The response will include the new issue number (e.g. MYAPP-1), its status (OPEN), and all other fields.