Quickstart Guide

Prerequisites

Before setting up CCDigital, ensure you have the following installed:

Java 17

Required runtime for Spring Boot 3.5.11

MySQL 8

Primary relational database

Docker

For blockchain networks (Fabric, Indy)

Verify Prerequisites

# Check Java version (must be 17+)
java -version

# Check MySQL
mysql --version

# Check Docker
docker --version
docker-compose --version

The project uses Maven Wrapper (./mvnw), so you don’t need Maven installed separately.

Installation Steps

Clone the Repository

Clone the CCDigital source code to your local machine:

git clone <repository-url>
cd CCDigital

Configure Environment Variables

CCDigital is configured entirely through environment variables. Create a configuration script based on the template below:

# Application basics
export APP_NAME='CCDigital'
export SERVER_PORT='8080'
export SERVER_SESSION_TIMEOUT='5m'

# Database connection
export DB_URL='jdbc:mysql://localhost:3306/ccdigital?useSSL=false&serverTimezone=UTC'
export DB_USERNAME='ccdigital_user'
export DB_PASSWORD='your_secure_password'

# Hibernate settings
export JPA_DDL_AUTO='none'
export JPA_SHOW_SQL='true'
export JPA_FORMAT_SQL='true'

# File storage
export CCDIGITAL_FS_BASE_PATH='/var/ccdigital/documents'

# ACA-Py / Indy agents
export ACAPY_VERIFIER_ADMIN_URL='http://localhost:8021'
export ACAPY_HOLDER_ADMIN_URL='http://localhost:8031'
export ACAPY_CRED_DEF_ID='<your-credential-definition-id>'
export ACAPY_PROOF_POLL_INTERVAL_MS='1000'
export ACAPY_PROOF_POLL_TIMEOUT_MS='20000'

# Indy configuration
export INDY_HOLDER_LABEL='holder'
export INDY_HOLDER_CONNECTION_ID='auto'
export INDY_USER_ACCESS_SYNC_ENABLED='true'
export INDY_USER_ACCESS_SYNC_PATH='/connections/{conn_id}/metadata'

# Fabric scripts
export FABRIC_WORKDIR='/path/to/fabric-client'
export FABRIC_NODE_BIN='/usr/bin/node'
export FABRIC_LIST_DOCS_SCRIPT='list-docs.js'
export FABRIC_BLOCK_READER_SCRIPT='read-block-by-ref.js'
export FABRIC_RECORD_ACCESS_SCRIPT='record-access-event.js'
export FABRIC_LIST_ACCESS_SCRIPT='list-access-events.js'
export FABRIC_SYNC_ALL_SCRIPT='sync-db-to-ledger.js'
export FABRIC_SYNC_PERSON_SCRIPT='sync-person.js'

# Indy tools
export INDY_TOOLS_WORKDIR='/path/to/indy-tools'
export INDY_VENV_ACTIVATE='source venv/bin/activate'
export INDY_SCRIPT='issue_credentials_from_db.py'
export EXTERNAL_TOOLS_TIMEOUT_SECONDS='180'

# Email configuration (for OTP and password recovery)
export MAIL_HOST='smtp.gmail.com'
export MAIL_PORT='587'
export MAIL_USERNAME='[email protected]'
export MAIL_PASSWORD='your-app-password'
export MAIL_SMTP_AUTH='true'
export MAIL_SMTP_STARTTLS_ENABLE='true'
export MAIL_SMTP_STARTTLS_REQUIRED='true'
export FORGOT_PASSWORD_MAIL_FROM='[email protected]'
export MAIL_TEST_CONNECTION='true'

Security Notice: Never commit .env files or configuration scripts with real credentials to version control. Use .gitignore to exclude them.

Save this as env-local.sh and source it:

source env-local.sh

Set Up MySQL Database

Create the database and user:

mysql -u root -p

CREATE DATABASE ccdigital CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'ccdigital_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON ccdigital.* TO 'ccdigital_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

If you have a database backup (SQL dump), import it:

mysql -h localhost -P 3306 -u ccdigital_user -p ccdigital < backup.sql

The database schema includes 22+ tables, views (v_documents, v_person_full_documents), stored procedures (sp_add_person_document, sp_create_user_with_person), and triggers for automatic versioning.

Create File Storage Directory

Create the base directory for document storage:

sudo mkdir -p /var/ccdigital/documents
sudo chown $USER:$USER /var/ccdigital/documents
chmod 755 /var/ccdigital/documents

This directory will contain subdirectories for each citizen, created automatically when persons are registered.

Run the Application

Start the Spring Boot application using Maven Wrapper:

./mvnw spring-boot:run

The application will start on the configured port (default: 8080).

On first run with JPA_DDL_AUTO=none, ensure your database schema is already initialized. Use validate to verify the schema matches your entities, or update for development (not recommended for production).

Alternative: Build and Run JAR

For production-like deployments:

# Build the application
./mvnw -DskipTests package spring-boot:repackage

# Run the JAR
java -jar target/CCDigital-1.0.0.jar

Access the Application

Open your browser and navigate to:

Admin Portal

http://localhost:8080/login/adminFor government operators

Issuer Portal

http://localhost:8080/login/issuerFor authorized institutions

User Portal

http://localhost:8080/login/userFor end-user citizens

Each module has its own authentication flow. Admin and Issuer use traditional username/password authentication, while Users authenticate with Indy verifiable credentials + MFA.

Configuration Reference

Core Application Settings

The application reads configuration from application.properties, which maps environment variables:

spring.application.name=${APP_NAME:CCDigital}
server.port=${SERVER_PORT:8080}
server.forward-headers-strategy=framework
server.servlet.session.timeout=${SERVER_SESSION_TIMEOUT:5m}

Key Points:

Session timeout defaults to 5 minutes of inactivity
Forward headers strategy enables proper URL construction behind reverse proxies (Caddy, nginx, Cloudflare)

Database Configuration

spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}

spring.jpa.hibernate.ddl-auto=${JPA_DDL_AUTO:none}
spring.jpa.show-sql=${JPA_SHOW_SQL:true}
spring.jpa.properties.hibernate.format_sql=${JPA_FORMAT_SQL:true}

DDL Auto Options:

none - No schema management (production)
validate - Validate schema matches entities
update - Update schema to match entities (dev only)
create - Drop and recreate schema on startup (testing only)

File Storage Configuration

ccdigital.fs.base-path=${CCDIGITAL_FS_BASE_PATH}
app.user-files-base-dir=${CCDIGITAL_FS_BASE_PATH}

Both properties must point to the same directory. The first is used by FileStorageService for writing, the second by UserDocsController for serving files with path validation.

Blockchain Network Configuration

ACA-Py / Indy Settings

acapy.verifier.admin=${ACAPY_VERIFIER_ADMIN_URL}
acapy.holder.admin=${ACAPY_HOLDER_ADMIN_URL}
acapy.cred-def-id=${ACAPY_CRED_DEF_ID}
acapy.proof.poll-interval-ms=${ACAPY_PROOF_POLL_INTERVAL_MS:1000}
acapy.proof.poll-timeout-ms=${ACAPY_PROOF_POLL_TIMEOUT_MS:20000}

ccdigital.indy.holder-connection-id=${INDY_HOLDER_CONNECTION_ID:auto}
ccdigital.indy.holder-label=${INDY_HOLDER_LABEL}
ccdigital.indy.user-access-sync-enabled=${INDY_USER_ACCESS_SYNC_ENABLED:true}

Connection ID Resolution:

Set to auto to automatically find the connection by holder-label
Or provide a specific connection ID

Fabric Script Configuration

external-tools.fabric.workdir=${FABRIC_WORKDIR}
external-tools.fabric.node-bin=${FABRIC_NODE_BIN}
external-tools.fabric.list-docs-script=${FABRIC_LIST_DOCS_SCRIPT}
external-tools.fabric.sync-all-script=${FABRIC_SYNC_ALL_SCRIPT}

Node.js scripts must be present in the workdir for blockchain synchronization.

Blockchain Network Setup (Optional)

Hyperledger Fabric Setup

Fabric integration is optional for basic testing. The application will work without it, but blockchain traceability features will be unavailable.

Prerequisites:

Docker & Docker Compose
Node.js LTS
Fabric binaries (peer, orderer, configtxlator)

Quick Setup:

Clone fabric-samples repository
Run bootstrap script to download binaries and images
Start test network with ./network.sh up createChannel
Deploy chaincode for document management
Configure Node.js client scripts with connection profiles
Set FABRIC_WORKDIR to the client script directory

See Architecture for detailed blockchain integration information.

Hyperledger Indy / ACA-Py Setup

Indy integration is required for end-user authentication. Without it, the user login flow will not function.

Prerequisites:

Docker & Docker Compose
Python 3.10+ with venv
Indy ledger (local pool for testing)

Quick Setup:

Start a local Indy ledger (von-network or similar)
Launch issuer ACA-Py agent with wallet and admin API
Launch holder ACA-Py agent with wallet and admin API
Register issuer DID on the ledger with transaction privileges
Create schema and credential definition
Establish connection between issuer and holder
Set ACAPY_CRED_DEF_ID to your credential definition ID

See Architecture for present-proof flow details.

Default Roles and Access

Security Configuration

CCDigital implements strict role-based access control via Spring Security (SecurityConfig):

Role	Prefix	Access Pattern	Login Path
Government Admin	`ROLE_GOBIERNO`	`/admin/`, `/api/`	`/login/admin`
Issuer	`ROLE_ISSUER`	`/issuer/**`	`/login/issuer`
End User	`ROLE_USER`	`/user/**`	`/login/user`

Public Endpoints

/ - Home page
/login/* - All login pages
/register/user/** - User registration flow
/static/**, /css/**, /js/** - Static resources

API endpoints under /api/** are restricted to admin users only. They provide programmatic access to system operations.

Security Features

Rate Limiting

Sensitive endpoints are protected by SensitiveEndpointRateLimitFilter:

# Environment configuration
export APP_SECURITY_RATE_LIMIT_ENABLED='true'
export APP_SECURITY_RATE_LIMIT_WINDOW_SECONDS='60'
export APP_SECURITY_RATE_LIMIT_MAX_REQUESTS_PER_WINDOW='10'

Signed URLs for Documents

Document access uses time-limited signed URLs via SignedUrlService:

export APP_SECURITY_SIGNED_URLS_SECRET='your-secret-key-min-32-chars'
export APP_SECURITY_SIGNED_URLS_TTL_SECONDS='300'

HTTPS Enforcement (Production)

export APP_SECURITY_REQUIRE_HTTPS='true'

TOTP Configuration

Customize Time-based One-Time Password settings:

export APP_SECURITY_TOTP_ISSUER='CCDigital'
export APP_SECURITY_TOTP_DIGITS='6'
export APP_SECURITY_TOTP_PERIOD_SECONDS='30'
export APP_SECURITY_TOTP_WINDOW_STEPS='1'

Verification

After starting the application, verify it’s working:

# Check application health
curl http://localhost:8080/

# Check database connection (look for connection logs)
tail -f logs/spring.log | grep -i "database\|mysql"

Common Issues

Database Connection Failed

Symptoms: Application fails to start with connection errorsSolutions:

Verify MySQL is running: systemctl status mysql
Check credentials in DB_URL, DB_USERNAME, DB_PASSWORD
Ensure database exists: mysql -u root -p -e "SHOW DATABASES LIKE 'ccdigital';"
Check firewall rules if MySQL is remote

Port Already in Use

Symptoms: Address already in use: bindSolutions:

Change SERVER_PORT to an available port
Kill the process using port 8080: lsof -ti:8080 | xargs kill -9

File Upload Fails

Symptoms: 403 Forbidden or “Ruta no permitida” errorSolutions:

Verify CCDIGITAL_FS_BASE_PATH directory exists and has write permissions
Ensure app.user-files-base-dir matches ccdigital.fs.base-path
Check SELinux/AppArmor policies if on Linux

Email OTP Not Sending

Symptoms: Login/registration fails at OTP verification stepSolutions:

Verify SMTP credentials in MAIL_USERNAME and MAIL_PASSWORD
For Gmail, use an App Password
Check MAIL_HOST and MAIL_PORT are correct for your provider
Set MAIL_TEST_CONNECTION=true to verify SMTP on startup

Next Steps

Architecture Deep Dive

Understand the system architecture, data flows, and blockchain integration

Admin Module

Learn how to manage persons, documents, and access governance

Issuer Module

Discover how institutions upload and manage official documents

User Module

Explore the citizen-facing authentication and document access flows

Production Deployment

For production deployment guides, consult your infrastructure documentation or Universidad El Bosque IT policies.

Get Started

User Modules

Core Features

Prerequisites

Java 17

MySQL 8

Docker

Verify Prerequisites

Installation Steps

Alternative: Build and Run JAR

Admin Portal

Issuer Portal

User Portal

Configuration Reference

Core Application Settings

Database Configuration

File Storage Configuration

Blockchain Network Configuration

ACA-Py / Indy Settings

Fabric Script Configuration

Blockchain Network Setup (Optional)

Default Roles and Access

Security Configuration

Public Endpoints

Security Features

Rate Limiting

Signed URLs for Documents

HTTPS Enforcement (Production)

TOTP Configuration

Verification

Common Issues

Next Steps

Architecture Deep Dive

Admin Module

Issuer Module

User Module

Production Deployment

Build docs developers (and LLMs) love

Get Started

User Modules

Core Features

​Prerequisites

Java 17

MySQL 8

Docker

​Verify Prerequisites

​Installation Steps

​Alternative: Build and Run JAR

Admin Portal

Issuer Portal

User Portal

​Configuration Reference

​Core Application Settings

​Database Configuration

​File Storage Configuration

​Blockchain Network Configuration

​ACA-Py / Indy Settings

​Fabric Script Configuration

​Blockchain Network Setup (Optional)

​Default Roles and Access

​Security Configuration

​Public Endpoints

​Security Features

​Rate Limiting

​Signed URLs for Documents

​HTTPS Enforcement (Production)

​TOTP Configuration

​Verification

​Common Issues

​Next Steps

Architecture Deep Dive

Admin Module

Issuer Module

User Module

​Production Deployment

Build docs developers (and LLMs) love

Prerequisites

Verify Prerequisites

Installation Steps

Alternative: Build and Run JAR

Configuration Reference

Core Application Settings

Database Configuration

File Storage Configuration

Blockchain Network Configuration

ACA-Py / Indy Settings

Fabric Script Configuration

Blockchain Network Setup (Optional)

Default Roles and Access

Security Configuration

Public Endpoints

Security Features

Rate Limiting

Signed URLs for Documents

HTTPS Enforcement (Production)

TOTP Configuration

Verification

Common Issues

Next Steps

Production Deployment