arena-compose-postgres/README.md

## arena-compose-postgres

This application consists of a frontend and a backend service, a PostgreSQL database, and a connector proxy, all orchestrated with Docker Compose.

### Services and Default Ports:

- `spiffworkflow-frontend`: The frontend user interface for the workflow application.
- `spiffworkflow-backend`: The backend service providing API endpoints for the frontend.
- `spiffdb`: A PostgreSQL database service used by the backend to store workflow data.
- `spiffworkflow-connector`: A connector proxy service for external integrations.

### Getting Started:

1. Ensure Docker and Docker Compose are installed on your system.
2. Clone the repository and navigate to the directory containing the `docker-compose.yml` file. The default ports are set in this file, but you can change them if needed.
3. Run `make up` to start all services. The services will be available on the following default ports:
4. Access the frontend at `http://localhost:8001`, where `8001` is the default port for the frontend service.
5. Access the backend API at `http://localhost:8000/v1.0`, where `8000` is the default port for the backend service.
6. Run `make down` to stop all services.

### Database Access:

To access the PostgreSQL database from within the `spiffdb` container, use the following command:

```sh
psql -U spiffuser -d spiffworkflow
```

The default username is `spiffuser` and the password is `spiffpass`, as configured in the `docker-compose.yml` file.

### Health Checks:

Health checks are configured for the `spiffworkflow-backend` and `spiffdb` services to ensure they are ready before dependent services start.

## Interacting with the API

The api is available at localhost:8000/v1.0 if you run `make up` in this repo.

Some of the followiong commands use `jq`, a useful tool for parsing JSON, in case you want to follow along with that by installing it.

```sh
# use a little script to get a token from the nonproduction openid server built in to spiffworkflow-backend and store it in a file.
# note that spiffworkflow supports any openid system, and this built in server should never be used in production.
./bin/get_token admin > /tmp/t

# create a process instance
curl -s -X POST localhost:8000/v1.0/process-instances/approvals:basic-approval -H "Authorization: Bearer $(cat /tmp/t)"

# let's assume that the previous request returned id 24. run that instance
curl -s -X POST localhost:8000/v1.0/process-instances/approvals:basic-approval/24/run -H "Authorization: Bearer $(cat /tmp/t)"

# it requires some human interaction. fetch the tasks that might need completing
curl -s "localhost:8000/v1.0/tasks?process_instance_id=24" -H "Authorization: Bearer $(cat /tmp/t)" | jq .

# the tasks API will return json like this:
# {
#   "results": [
#     {
#       "id": "64c3738c-0dc1-48f6-98fc-7db41e03dab3",
#       "form_file_name": "request-schema.json",
#       "task_type": "UserTask",
#       "ui_form_file_name": "request-uischema.json",
#       "task_status": "READY",
#       [SNIP]
#       "assigned_user_group_identifier": null,
#       "potential_owner_usernames": "admin@spiffworkflow.org"
#     }
#   ],
# }

# it looks like this task uses the request-schema.json form. let's fetch it.
curl -s "localhost:8000/v1.0/process-models/approvals:basic-approval/files/request-schema.json" -H "Authorization: Bearer $(cat /tmp/t)" | jq -r .file_contents

# this response tells us that we need a request_item when submitting the task

# submit the task based on the information from the tasks response
curl -X PUT -H 'Content-type: application/json' -d '{"request_item": "apple"}' "localhost:8000/v1.0/tasks/24/64c3738c-0dc1-48f6-98fc-7db41e03dab3" -H "Authorization: Bearer $(cat /tmp/t)" | jq .

# next the process instance will proceed to the approval task.
# its form can be inspected and the task submitted in the same way as above
curl -s "localhost:8000/v1.0/process-models/approvals:basic-approval/files/approval-schema.json" -H "Authorization: Bearer $(cat /tmp/t)" | jq -r .file_contents
curl -X PUT -H 'Content-type: application/json' -d '{"is_approved": false, "comments": "looks good to me"}' "localhost:8000/v1.0/tasks/24/f796b2d5-8d7c-423f-ac1a-2cfbc95f4c04" -H "Authorization: Bearer $(cat /tmp/t)" | jq .

# at this point, after the two PUT requests, you can check on the instance,
# and it will hopefully be completed if you said is_approved false
curl -s localhost:8000/v1.0/process-instances/approvals:basic-approval/24 -H "Authorization: Bearer $(cat /tmp/t)" | jq .
```
If you approved it by setting is_approved to `true`, the instance will be waiting on a final manual task that is just giving you a message about how you approved the item.
Hopefully this has been helpful in describing how to access some of the important functionality via the API.

### Troubleshooting:

If you encounter any issues with the services, check the logs using `docker-compose logs`.