Quick Start Guide

Get Med Agenda running locally in under 5 minutes using Docker Compose. This guide will walk you through setting up the complete application stack including the backend API, frontend, and database.

This quick start is designed for development and testing. For production deployment, see the Deployment Guide.

Prerequisites

Before you begin, ensure you have the following installed on your system:

Docker & Docker Compose

Docker Engine 20.10+ and Docker Compose V2+

# Verify Docker installation
docker --version
docker compose version

Download Docker Desktop from docker.com for Windows and Mac, or install Docker Engine for Linux.

Git

Git for cloning the repository

# Verify Git installation
git --version

System Requirements

Minimum recommended specifications:

CPU: 2 cores
RAM: 4GB available
Disk: 2GB free space
OS: Linux, macOS, or Windows with WSL2

Installation

Clone the Repository

Clone the Med Agenda repository from GitHub:

git clone https://github.com/nathanmota-dev/med-agenda.git
cd med-agenda

This will download the complete source code including both backend and frontend applications.

Configure Environment Variables

Create a .env file in the backend directory with your configuration:

cd backend/gestaoConsultasMedicas
cp .env.example .env

Edit the .env file with your settings:

# Database Configuration
SPRING_DATASOURCE_URL=jdbc:postgresql://your-database-host:5432/medagenda
SPRING_DATASOURCE_USERNAME=your_username
SPRING_DATASOURCE_PASSWORD=your_password

# Email Service (Resend)
RESEND_API_KEY=your_resend_api_key

# Application Settings
SERVER_PORT=8080
SPRING_JPA_HIBERNATE_DDL_AUTO=update
SPRING_JPA_SHOW_SQL=true

Database Setup Required: You need a PostgreSQL database. We recommend using Neon.tech for a free managed PostgreSQL instance.

Get a Free PostgreSQL Database

Sign up at Neon.tech
Create a new project
Copy the connection string
Update SPRING_DATASOURCE_URL in your .env file

Get Email Service API Key

Sign up at Resend.com
Create an API key
Update RESEND_API_KEY in your .env file

The email service is optional for testing. The application will work without it, but appointment confirmation emails won’t be sent.

Build and Run with Docker Compose

Build and start the application using Docker Compose:

# From the backend directory
docker compose up --build

This command will:

Build the Spring Boot backend application
Create a Docker image named med-agenda:latest
Start the API server on port 8080
Load environment variables from .env

The first build may take 5-10 minutes as Maven downloads dependencies. Subsequent builds will be much faster thanks to Docker layer caching.

Run in Detached Mode

To run the containers in the background:

docker compose up -d

View Logs

docker compose logs -f api

Start the Frontend

In a new terminal, navigate to the frontend directory and start the development server:

cd frontend
npm install
npm run dev

The frontend will be available at http://localhost:5173

Make sure you have Node.js 18+ and npm installed. Check with node --version and npm --version.

Verify the Installation

Test that everything is working:Backend Health Check:

curl http://localhost:8080/

You should see: Hello WorldFrontend Access: Open your browser to http://localhost:5173You should see the Med Agenda login page.

First Steps

Now that Med Agenda is running, let’s set up your first users and test the system.

Create an Admin Account

Create an administrator account to manage the system:

curl -X POST http://localhost:8080/admin/create \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "admin123",
    "name": "System Administrator"
  }'

Save the returned admin ID for future reference.

Add a doctor to the system:

curl -X POST http://localhost:8080/doctor/create \
  -H "Content-Type: application/json" \
  -d '{
    "crm": "123456789",
    "email": "[email protected]",
    "password": "doctor123",
    "name": "Dr. Maria Silva",
    "specialty": "Cardiologia",
    "telephone": "5511999999999",
    "consultationValue": 200.00
  }'

The CRM is the Brazilian medical license number. Use any 9-digit number for testing.

Create a patient account:

curl -X POST http://localhost:8080/patients/create \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678901",
    "email": "[email protected]",
    "password": "patient123",
    "name": "João Santos",
    "dateOfBirth": "1990-01-15",
    "address": "Rua Example, 123",
    "medicalHistory": "No previous conditions"
  }'

CPF is the Brazilian national ID. Use any 11-digit number for testing.

Schedule a Consultation

Book your first appointment:

curl -X POST http://localhost:8080/consultations/create \
  -H "Content-Type: application/json" \
  -d '{
    "patient": {
      "cpf": "12345678901"
    },
    "doctor": {
      "crm": "123456789"
    },
    "dateTime": "2026-03-15T14:00:00",
    "isUrgent": false,
    "observation": "Regular checkup"
  }'

The patient will receive an email confirmation (if Resend is configured).

Explore the Frontend

Open the frontend at http://localhost:5173 and:

Login as Patient: Use CPF 12345678901 and password patient123
View Appointments: See your scheduled consultation
Login as Doctor: Use CRM 123456789 and password doctor123
Manage Consultations: View patient appointments

API Testing

Explore the REST API with these common operations:

List All Consultations

curl http://localhost:8080/consultations/all

Get Patient History

curl http://localhost:8080/consultations/patient-history/12345678901

Search Doctors by Specialty

curl "http://localhost:8080/doctor/search?specialty=Cardiologia"

Create a Diagnosis

curl -X POST http://localhost:8080/diagnosis \
  -H "Content-Type: application/json" \
  -d '{
    "descricao": "Hipertensão arterial sistêmica",
    "data": "2026-03-15",
    "consulta": {
      "consultationId": "<consultation-uuid>"
    },
    "cid": "I10"
  }'

Complete API Reference

Explore all available API endpoints with detailed documentation

Stopping the Application

To stop the running containers:

# Stop and remove containers
docker compose down

# Stop, remove containers, and delete volumes
docker compose down -v

To stop the frontend development server, press Ctrl+C in the terminal.

Troubleshooting

Port 8080 already in use

If port 8080 is already occupied, you can change it in two ways:

Modify docker-compose.yml:

ports:
  - "8081:8080"  # Use port 8081 instead

Set in .env file:

SERVER_PORT=8081

Database connection failed

Ensure your database credentials are correct in the .env file:

# Test PostgreSQL connection
psql -h your-host -U your-username -d your-database

Common issues:

Incorrect hostname or port
Wrong username/password
Database doesn’t exist (create it first)
Firewall blocking connections

Email notifications not working

Email functionality requires a valid Resend API key:

Verify your API key at Resend Dashboard
Ensure RESEND_API_KEY is set in .env
Check application logs for email errors

The application will work without email, but notifications won’t be sent.

Frontend can't connect to backend

Ensure the API URL is correctly configured in the frontend:Check frontend/src/api/config.ts or similar configuration file:

const API_BASE_URL = 'http://localhost:8080';

Also verify CORS is enabled in the backend (it should be by default).

Docker build fails

Common solutions:

Clear Docker cache:

docker builder prune
docker compose build --no-cache

Check disk space:

docker system df
docker system prune

Verify Java and Maven in the Dockerfile

Next Steps

Now that you have Med Agenda running, explore these resources:

Features Overview

Learn about all available features

API Documentation

Complete REST API reference

User Guides

Detailed guides for patients and doctors

Production Deployment

Deploy Med Agenda to production

Security Notice: The default credentials in this guide are for development only. Always use strong passwords and proper authentication in production environments.

Overview

User Guides

Core Features

Deployment

Development

Quick Start

Quick Start Guide

Prerequisites

Installation

Get a Free PostgreSQL Database

Get Email Service API Key

Run in Detached Mode

View Logs

First Steps

API Testing

List All Consultations

Get Patient History

Search Doctors by Specialty

Create a Diagnosis

Complete API Reference

Stopping the Application

Troubleshooting

Next Steps

Features Overview

API Documentation

User Guides

Production Deployment

Build docs developers (and LLMs) love

Overview

User Guides

Core Features

Deployment

Development

​Quick Start Guide

​Prerequisites

​Installation

​Get a Free PostgreSQL Database

​Get Email Service API Key

​Run in Detached Mode

​View Logs

​First Steps

​API Testing

​List All Consultations

​Get Patient History

​Search Doctors by Specialty

​Create a Diagnosis

Complete API Reference

​Stopping the Application

​Troubleshooting

​Next Steps

Features Overview

API Documentation

User Guides

Production Deployment

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Installation

Get a Free PostgreSQL Database

Get Email Service API Key

Run in Detached Mode

View Logs

First Steps

API Testing

List All Consultations

Get Patient History

Search Doctors by Specialty

Create a Diagnosis

Stopping the Application

Troubleshooting

Next Steps