Skip to main content

​
Prerequisites

Before installing Secure Link API, ensure you have the following installed:
  • Java 21+ (required)
  • Maven 3.6+ (for building the project)
  • MySQL 8.4+ (for development and production)
  • Git (for cloning the repository)

​
Installation Steps

1

Clone the Repository

Clone the Secure Link API repository from GitHub:
git clone https://github.com/WalysonGomes/secure-link-api.git
cd secure-link-api/backend
The main branch contains the API-only version (v1.0.0-api). For the full-stack version with Angular frontend, check out the full branch.
2

Configure Environment Variables

Copy the example environment file and configure your settings:
cp .env.example .env
Edit the .env file with your MySQL database credentials:
.env
BASE_URL=http://localhost:8080
DB_HOST=localhost
DB_PORT=3307
DB_NAME=secure_link
DB_USERNAME=your_username
DB_PASSWORD=your_password
Never commit the .env file to version control. It’s already included in .gitignore.
3

Set Up MySQL Database

You can either install MySQL locally or use Docker. For Docker, see the Docker Deployment guide.Manual MySQL Setup:
CREATE DATABASE secure_link CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'your_username'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON secure_link.* TO 'your_username'@'localhost';
FLUSH PRIVILEGES;
Flyway migrations will automatically create the database schema on first run.
4

Build the Project

Build the project using Maven:
mvn clean install
This will:
  • Download all dependencies
  • Compile the Java code
  • Run unit tests
  • Package the application as a JAR file
5

Run the Application

Start the application with the dev profile:
SPRING_PROFILES_ACTIVE=dev mvn spring-boot:run
Or run the packaged JAR:
java -jar target/secure-link-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev
The API will start on http://localhost:8080
6

Verify Installation

Check that the API is running by accessing the health endpoint:
curl http://localhost:8080/actuator/health
Expected response:
{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "diskSpace": { "status": "UP" },
    "expirationJob": { "status": "UP" },
    "storage": { "status": "UP" }
  }
}

​
Running Tests

The project uses the test profile with an in-memory H2 database for testing: 
mvn test
Tests cover:
  • Link creation and validation
  • File upload functionality
  • Access control and expiration logic
  • Password protection
  • Audit logging
  • Metrics collection

​
Development Workflow

For active development, you can use Spring Boot DevTools for hot reloading: 
SPRING_PROFILES_ACTIVE=dev mvn spring-boot:run
The application automatically creates the /tmp/uploads/ directory for file storage. You can customize this path in the configuration.

​
Troubleshooting

​
Database Connection Issues

If you encounter database connection errors:
  1. Verify MySQL is running: mysql -u your_username -p
  2. Check the database exists: SHOW DATABASES;
  3. Verify credentials in .env file
  4. Ensure the port matches your MySQL configuration

​
Port Already in Use

If port 8080 is already in use, change it in application.properties: 
server.port=8081

​
Flyway Migration Errors

If Flyway fails to migrate: 
# Check Flyway status
mvn flyway:info

# Repair if needed
mvn flyway:repair

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us