> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Prerequisites
> Check the infrastructure, dependencies, authentication, and file-format requirements your environment needs before you deploy Matcher for reconciliation.
Before deploying Matcher, ensure that your environment meets the requirements described on this page.
These prerequisites define the baseline for running reconciliation reliably in development and production environments.
## System requirements
***
### Infrastructure
| Component | Minimum / recommended | Purpose |
| ----------- | --------------------- | -------------------------------------------------- |
| **CPU** | 2 cores / 4+ cores | Matching and scoring logic is CPU-intensive |
| **Memory** | 2 GB / 4+ GB | In-memory processing of transaction batches |
| **Storage** | 10 GB / 50+ GB | Persistent storage for transactions and audit logs |
### Dependencies
Matcher depends on the following services:
* **PostgreSQL 15+**: Primary data store for reconciliation contexts, transactions, matches, and audit logs.
* **Redis 7+**: Used for caching, duplicate detection, distributed locking, and idempotency control.
* **RabbitMQ 3.12+**: Message broker for asynchronous processing across bounded contexts.
### Runtime
Matcher supports the following runtimes and tooling:
* **Go 1.26+** (only required when building from source)
* **Docker 24+** and **Docker Compose 2.20+** for containerized deployments
* **Kubernetes 1.28+** for production-grade deployments using Helm
## Optional: reconciling Midaz data
***
Matcher pairs naturally with Midaz Ledger, but there is **no live connector between them** — Matcher has no `MIDAZ_API_URL` and opens no connection to Midaz. Reconciling Midaz data is entirely optional; Matcher works as a stand-alone product reconciling any data sources.
### When to reconcile Midaz data
Reconcile ledger data from Midaz if:
* You use Midaz as your ledger system
* You want to reconcile Midaz postings against external sources (bank statements, gateway reports)
### When Midaz is not involved
Matcher works independently when:
* Reconciling between external systems (banks, ERPs, payment processors)
* Using a different ledger system
* Importing ledger data via CSV/JSON/XML files
### How it works
Matcher reconciles Midaz data the same way it ingests any source — by import, not a live query:
1. Export the ledger data for the period you want to reconcile.
2. Import that export into a Matcher context as a source of type `LEDGER`.
3. Import the counterparty data (bank statement or gateway report) as the other side.
4. Matcher matches the two sides using your match rules.
See the [Matcher and Midaz](/en/matcher/integrations/matcher-midaz-integration) guide for the full flow.
## Authentication
***
Matcher uses **lib-auth** for authentication and authorization, consistent with the rest of the Lerian ecosystem.
### Authentication flow
1. The client obtains a JWT from the identity provider
2. The token is sent in the `Authorization: Bearer ` header
3. Matcher validates the token via lib-auth
4. Tenant identity and permissions are extracted from token claims
### Required permissions
Access to Matcher features is controlled through fine-grained permissions:
| Permission | Description |
| -------------------- | ------------------------------ |
| `contexts:create` | Create reconciliation contexts |
| `contexts:read` | View context configuration |
| `rules:create` | Create and update match rules |
| `imports:create` | Upload transaction files |
| `match-runs:run` | Execute matching jobs |
| `exceptions:read` | View exceptions |
| `exceptions:resolve` | Resolve exceptions |
| `reports:read` | Access reports and audit views |
### Single-tenant mode
If authentication is disabled or no tenant identifier is present in the JWT, Matcher runs in single-tenant mode using a default tenant.
```bash theme={null}
# Default tenant configuration (single-tenant mode)
DEFAULT_TENANT_ID=11111111-1111-1111-1111-111111111111
DEFAULT_TENANT_SLUG=default
```
## Supported file formats
***
Matcher accepts transaction data in the following formats.
Each format has specific structural requirements for successful ingestion.
### CSV (comma-separated values)
Commonly used for bank statements and exports.
**Requirements:**
* Header row is required
* UTF-8 encoding
* Comma delimiter (configurable)
* Quoted fields for values containing delimiters
**Example:**
```csv theme={null}
transaction_id,amount,currency,date,reference
TXN-001,1000.00,USD,2024-01-15,Invoice payment
TXN-002,-250.50,USD,2024-01-16,Refund
```
### JSON (javascript object notation)
Recommended for API-based integrations.
**Requirements:**
* Valid JSON array of transaction objects
* UTF-8 encoding
* Consistent field names across records
**Example:**
```json theme={null}
[
{
"transaction_id": "TXN-001",
"amount": 1000.0,
"currency": "USD",
"date": "2024-01-15",
"reference": "Invoice payment"
}
]
```
### XML (extensible markup language)
Common in enterprise and banking integrations.
**Requirements:**
* Single root element
* UTF-8 encoding
* Consistent element structure
**Example:**
```xml theme={null}
TXN-001
1000.00
USD
2024-01-15
Invoice payment
```
### File size limits
| Limit | Default | Configurable via |
| ----------------------------- | ------- | ----------------------------------------------------- |
| Maximum upload file size | 1 GiB | `INGESTION_MAX_UPLOAD_BYTES` (streaming upload route) |
| Maximum buffered request body | 100 MiB | `HTTP_BODY_LIMIT_BYTES` (non-upload requests) |
| Maximum transactions per file | 100,000 | Context-level configuration |
## Network requirements
***
### Inbound access
Matcher exposes a REST API that must be reachable by clients:
| Port | Protocol | Purpose |
| ---- | ---------- | ----------------------------------------------------------------- |
| 4018 | HTTP/HTTPS | API server (default `:4018`; serves HTTPS when TLS is configured) |
### Outbound access
Matcher must be able to reach the following services:
| Service | Purpose | Required |
| ----------------- | ------------------------ | ---------------------------- |
| PostgreSQL | Data persistence | Yes |
| Redis | Caching and coordination | Yes |
| RabbitMQ | Messaging | Yes |
| Auth service | Token validation | If authentication is enabled |
| JIRA / ServiceNow | Exception routing | Optional |
| Custom webhooks | Event notifications | Optional |
### TLS configuration
For production environments, configure TLS:
```bash theme={null}
SERVER_TLS_CERT_FILE=/path/to/cert.pem
SERVER_TLS_KEY_FILE=/path/to/key.pem
```
## Environment checklist
***
Before proceeding with installation, confirm that:
* **Infrastructure is ready**: PostgreSQL, Redis, and RabbitMQ are running and accessible
* **Authentication is configured**: Auth service is available, or auth is explicitly disabled
* **Network access is validated**: Required inbound and outbound connectivity is in place
* **Credentials are available**: Database credentials and API tokens are configured
* **Sample data is prepared**: Transaction files are ready for testing (see [Quick Start](/en/matcher/getting-started/matcher-quick-start))
## Next steps
***
Deploy Matcher using Docker or Kubernetes.
Run your first reconciliation.