Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuillermoNavarro/Proyecto_comunidades/llms.txt

Use this file to discover all available pages before exploring further.

The Comunidades Vecinos backend is a Spring Boot 4 application running on Java 21. It exposes a stateless REST API secured with JWT authentication and connects to a MariaDB database. Before starting the server for the first time, you need to supply three environment variables and verify that your filesystem upload paths exist.

​
Environment Variables

The following variables are required at runtime. The application will fail to start if any of them are missing, because Spring will be unable to resolve the ${…} placeholders in application.properties.
​
DB_USER
string
required
The MariaDB (or MySQL) username used to connect to the comunidad_vecinos database.
​
DB_PASSWORD
string
required
The password for the database user specified in DB_USER.
​
JWT_SECRET
string
required
A Base64-encoded secret key used to sign and verify JSON Web Tokens with HMAC-SHA256. Use a randomly generated string of at least 32 bytes (256 bits). You can generate one with openssl rand -base64 32.
Never commit real values for these variables to source control. Use a .env file, a secrets manager, or your deployment platform’s secrets injection mechanism.

​
Application Properties Reference

The full configuration lives in backend/src/main/resources/application.properties. The table below covers every property that you are likely to need to change for a new environment.
PropertyDefaultDescription
server.port8081The HTTP port the embedded Tomcat server listens on.
spring.datasource.urljdbc:mariadb://localhost:3306/comunidad_vecinosFull JDBC connection URL. Change localhost and 3306 if your database is on a different host or port.
spring.datasource.username${DB_USER}Resolved from the environment variable at startup.
spring.datasource.password${DB_PASSWORD}Resolved from the environment variable at startup.
spring.jpa.hibernate.ddl-autoupdateHibernate schema management strategy. update creates missing tables and adds new columns on startup without dropping existing data.
app.upload.dir/var/www/comunidades/documents/Absolute filesystem path where uploaded PDF documents are stored. The directory must exist and be writable by the process user.
app.upload.images.dir/var/www/comunidades/images/Absolute filesystem path for uploaded images. Must exist and be writable.
spring.servlet.multipart.max-file-size15MBMaximum size for a single uploaded file. Increase this value if residents need to upload larger documents.
spring.mail.hostlocalhostSMTP server hostname. Set to your provider’s address for production.
spring.mail.port1025SMTP port. 1025 is the default for MailHog/Mailpit. Use 587 (STARTTLS) or 465 (SSL) for production.
spring.mail.properties.mail.smtp.authfalseEnable SMTP authentication. Set to true for production mail providers.
spring.mail.properties.mail.smtp.starttls.enablefalseEnable STARTTLS encryption. Set to true when using port 587 with a real SMTP server.
jwt.secret${JWT_SECRET}Resolved from the environment variable. Must be a valid Base64 string.

​
Running the Backend

1

Set your environment variables

Export the required variables in your shell session before running the application:
export DB_USER=comunidad_user
export DB_PASSWORD=your_db_password
export JWT_SECRET=$(openssl rand -base64 32)
2

Start the development server

From the backend/ directory, use the Maven wrapper to compile and launch the application:
./mvnw spring-boot:run
You can also inline the environment variables for a one-liner:
DB_USER=root DB_PASSWORD=secret JWT_SECRET=mysecretkey ./mvnw spring-boot:run
The server will start on http://localhost:8081.
3

Build a production JAR

Compile and package the application into a self-contained executable JAR:
./mvnw clean package
Then run it with your environment variables set:
java -jar target/comunidad-backend-0.0.1-SNAPSHOT.jar
spring.jpa.hibernate.ddl-auto=update is convenient during development because it automatically creates or alters tables to match your JPA entities on every startup. For production deployments, consider switching to validate and managing schema changes with a dedicated migration tool such as Flyway or Liquibase. This prevents unintended schema modifications and gives you a full audit trail of database changes.

​
Mail Configuration

By default, the application expects a local SMTP development server (such as MailHog or Mailpit) listening on localhost:1025. These tools capture outgoing emails and display them in a web UI — no real emails are sent. To connect to a production SMTP provider, update the following properties: 
spring.mail.host=smtp.your-provider.com
spring.mail.port=587
spring.mail.username=your_smtp_user
spring.mail.password=your_smtp_password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
Common production SMTP providers include SendGrid, Mailgun, Amazon SES, and Brevo (formerly Sendinblue). Each provides its own host, port, and credential values.

​
Swagger UI and API Docs

The API documentation is automatically generated by springdoc-openapi and is publicly accessible without authentication — no JWT token is required to browse the docs.
URLDescription
http://localhost:8081/swagger-ui/index.htmlInteractive Swagger UI for exploring and testing all endpoints.
http://localhost:8081/v3/api-docsRaw OpenAPI 3 JSON specification, suitable for import into Postman or other API clients.
The /swagger-ui/**, /v3/api-docs/**, and /api/login paths are explicitly allowed in SecurityConfig without requiring a Bearer token. All other endpoints require a valid JWT in the Authorization: Bearer <token> header.

Build docs developers (and LLMs) love

Get started for freeTalk to us