# Getting Started

This guide will help you get the STA Connector up and running quickly.

## Prerequisites

Before you begin, ensure you have the following:

### Required

- **Elixir 1.15+ and Erlang/OTP 26+** - The backend runtime
- **BCB Sisbacen Credentials** - Username and password for STA WebService

### Optional

- **Docker & Docker Compose** - For containerized deployment (recommended)
- **PostgreSQL 15+** - Required for production deployments
- **Node.js 20+** - For building the admin portal from source

## Quick Start with Docker

The fastest way to get started is using Docker Compose:

```bash
# Clone the repository
git clone https://github.com/MonetarieBR/sta
cd sta

# Copy and configure environment variables
cp deployments/.env.example deployments/.env
nano deployments/.env  # Edit with your credentials

# Start all services
cd deployments
docker-compose up -d

# Check service status
docker-compose ps
```

This will start:
- STA Connector backend on port 4000
- Admin Portal on port 3000

Access the admin portal at [http://localhost:3000](http://localhost:3000).

**Demo credentials:** admin / admin123

## Environment Variables

Before starting, configure the required environment variables in `deployments/.env`:

```bash
# Required: Phoenix Configuration
DATABASE_URL=ecto://postgres:postgres@localhost/sta_connector_dev
SECRET_KEY_BASE=generate_a_64_byte_secret_key_here
PHX_HOST=localhost

# Required: STA (BCB) Credentials
STA_USERNAME=your_sisbacen_username
STA_PASSWORD=your_sisbacen_password

# Required: API Authentication
OUTBOUND_API_KEY=generate_a_secure_api_key_here
ADMIN_PASSWORD=generate_a_secure_admin_password

# Required: Monetarie STA Integration
MONETARIE_STA_TOKEN=your_monetarie_sta_bearer_token

# Optional: Production settings
PHX_SERVER=true
PORT=4000
```

## Manual Installation

For development or customized deployments, you can build and run the services manually.

### 1. Clone and Setup

```bash
git clone https://github.com/MonetarieBR/sta
cd sta
```

### 2. Setup the Backend

```bash
cd backend && mix deps.get && mix ecto.setup && mix phx.server
```

This will:
- Install Elixir dependencies
- Create and migrate the database
- Start the Phoenix server on port 4000

### 3. Setup the Frontend

In a separate terminal:

```bash
cd frontend && npm install && npm run dev
```

### 4. Configure

Configuration is managed through Elixir config files. Edit `config/dev.exs` for development:

```elixir
import Config

config :sta_connector, StaConnector.Repo,
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  database: "sta_connector_dev",
  stacktrace: true,
  show_sensitive_data_on_connection_error: true,
  pool_size: 10

config :sta_connector, StaConnectorWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 4000],
  check_origin: false,
  code_reloader: true,
  debug_errors: true,
  secret_key_base: "your_secret_key_base_here",
  watchers: []

config :sta_connector, :sta,
  environment: :homologation,
  username: System.get_env("STA_USERNAME"),
  password: System.get_env("STA_PASSWORD"),
  institution_code: "12345",
  timeout: 30_000,
  max_retries: 3

config :sta_connector, :poller,
  enabled: true,
  interval: 30_000,
  systems: [:ccs, :cir, :spi, :dict],
  batch_size: 10

config :sta_connector, :routes,
  ccs: [url: "https://staapi-planner.monetarie.com.br/api/v1/ccs", enabled: true],
  cir: [url: "https://staapi-planner.monetarie.com.br/api/v1/cir", enabled: true],
  spi: [url: "https://staapi-planner.monetarie.com.br/api/v1/spi", enabled: true],
  dict: [url: "https://staapi-planner.monetarie.com.br/api/v1/dict", enabled: true]
```

For production, use environment variables in `config/runtime.exs`:

```elixir
import Config

if config_env() == :prod do
  database_url =
    System.get_env("DATABASE_URL") ||
      raise "DATABASE_URL environment variable is missing"

  config :sta_connector, StaConnector.Repo,
    url: database_url,
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")

  secret_key_base =
    System.get_env("SECRET_KEY_BASE") ||
      raise "SECRET_KEY_BASE environment variable is missing"

  host = System.get_env("PHX_HOST") || "localhost"
  port = String.to_integer(System.get_env("PORT") || "4000")

  config :sta_connector, StaConnectorWeb.Endpoint,
    url: [host: host, port: 443, scheme: "https"],
    http: [ip: {0, 0, 0, 0}, port: port],
    secret_key_base: secret_key_base
end
```

## Verify Installation

### Health Check

Check the connector health:

```bash
curl http://localhost:4000/api/v1/health
```

Expected response:

```json
{
  "status": "healthy",
  "sta_connection": "ok",
  "database": "ok",
  "uptime_seconds": 120,
  "version": "1.0.0"
}
```

### Admin API Health

```bash
curl -u admin:admin123 http://localhost:4000/admin/health
```

Expected response:

```json
{
  "status": "healthy",
  "version": "1.0.0",
  "checks": {
    "store": "healthy",
    "metrics": "healthy",
    "poller": "idle"
  },
  "timestamp": "2026-01-31T10:30:00Z"
}
```

### Admin Portal

Open the admin portal and verify:

1. Dashboard shows system status as "Healthy"
2. Configuration page loads with current settings
3. Metrics display is updating

**Demo credentials:** admin / admin123

## Next Steps

- [Configuration Guide](/guide/configuration) - Detailed configuration options
- [Inbound Pipeline](/guide/inbound) - Set up file polling from BCB
- [Outbound Pipeline](/guide/outbound) - Send files to BCB
- [API Reference](/api/) - REST API documentation

## Troubleshooting

### Database Connection Failed

Ensure PostgreSQL is running and the database exists:

```bash
mix ecto.create
mix ecto.migrate
```

Or check your `DATABASE_URL` environment variable is correct.

### STA Connection Failed

1. Check your Sisbacen credentials
2. Verify network connectivity to BCB:
   - Homologation: `https://sta-h.bcb.gov.br/staws`
   - Production: `https://sta.bcb.gov.br/staws`
3. Check firewall rules allow HTTPS outbound

### Port Already in Use

Specify a different port:

```bash
PORT=4001 mix phx.server
```

Or in `config/dev.exs`:

```elixir
config :sta_connector, StaConnectorWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 4001]
```

### Permission Denied (Docker)

Ensure the data volume has correct permissions:

```bash
docker-compose down
docker volume rm deployments_connector-data
docker-compose up -d
```

For more help, see the [Troubleshooting Guide](/troubleshooting) or open an issue on GitHub.