Skip to main content

Quick Start (Local)

Run FormKiQ locally using Docker for development and testing. This guide will help you:

  • Set up a local FormKiQ environment
  • Upload and retrieve documents
  • Search documents
  • Manage document tags

Prerequisites​

System Requirements:

  • 4GB RAM minimum
  • 10GB free disk space

Launching FormKiQ​

FormKiQ can be launched using Docker Compose.

This will create the following local services:

  • formkiq/api-server
  • minio
  • dynamodb
  • keycloak
  • typesense

Using the following docker-compose.yml file you can launch FormKiQ local using

docker-compose -f docker-compose.yml up -d

OR

use the following bash script.

curl -O https://raw.githubusercontent.com/formkiq/formkiq-core/refs/heads/1.19.1/apps/netty-server/docker-compose.yml && docker-compose up

The local stack pulls MinIO from formkiq/minio on Docker Hub. If the repository is private or your Docker Hub pull limit has been reached, run docker login with an account that has access before starting the stack.

Authentication​

The default API key is "changeme". Add it to your HTTP headers:

-H "Authorization: changeme"
note

You will likely want to change this, even on your local installation.

Document Operations​

Upload Documents​

note

Maximum file size: 10MB. For larger files, use GET /documents/upload to generate a presigned URL.

Upload Text Content​

curl -X POST -H "Authorization: changeme" \
-d '{ "path": "user.json","contentType": "application/json", "content": "{\"name\":\"John Smith\"}","tags": [{"key": "lastName","value": "Smith"}]}' \
"http://localhost:8080/documents"

Upload Base64 Content​

# Create base64 content
echo -n 'This is a test content' | openssl base64
# Returns: VGhpcyBpcyBhIHRlc3QgY29udGVudA==

# Upload document
curl -X POST -H "Authorization: changeme" \
-d '{ "isBase64":true, "path": "test.txt","contentType": "text/plain", "content": "VGhpcyBpcyBhIHRlc3QgY29udGVudA=="}' \
"http://localhost:8080/documents"

Retrieve Documents​

List today's documents:

curl -H "Authorization: changeme" "http://localhost:8080/documents" | jq

Get document by ID:

curl -H "Authorization: changeme" "http://localhost:8080/documents/<DOCUMENT_ID>" | jq

Get document download URL:

curl -H "Authorization: changeme" "http://localhost:8080/documents/<DOCUMENT_ID>/url" | jq

Search Documents​

Search by tag key:

curl -X POST -H "Authorization: changeme" \
-d '{"query": {"tag": {"key": "lastName"}}}' "http://localhost:8080/search" | jq

Search by key and value:

curl -X POST -H "Authorization: changeme" \
-d '{"query": {"tag": {"key": "lastName", "eq": "Smith"}}}' "http://localhost:8080/search" | jq

Search with begins-with (case sensitive):

curl -X POST -H "Authorization: changeme" \
-d '{"query": {"tag": {"key": "lastName","beginsWith":"S"}}}' "http://localhost:8080/search" | jq

Document Tags​

Add tag:

curl -X POST -H "Authorization: changeme" \
-d '{"key": "firstName","value": "John"}' "http://localhost:8080/documents/<DOCUMENT_ID>/tags"

List tags:

curl -H "Authorization: changeme" "http://localhost:8080/documents/<DOCUMENT_ID>/tags" | jq

Web Console Access​

Access the web console at http://localhost

Login credentials:

Cleanup​

Stop and remove containers:

docker-compose down

Remove persistent data:

rm -rf ./formkiq ./typesense-data

Troubleshooting​

Common issues and solutions:

  1. Port conflicts

    • Error: "port is already allocated"
    • Solution: Stop services using ports 80, 8080, 9000, or 8108

  2. Container startup failure

    • Check logs: docker-compose logs
    • Ensure sufficient system resources

For additional help:

For more API endpoints, see the FormKiQ API Reference.