Skip to main content

Backend: configuració i setup en local

Aquest document descriu com preparar l’entorn del backend, les dependències clau, la configuració base de Spring Boot i la base de dades per al projecte Line Dance Platform (LDP), i com arrencar-lo en local.

1. Requisits del sistema​

Java Development Kit (JDK)​

Apache Maven​

Docker Desktop​

Git​

IDE recomanat​

  • IntelliJ IDEA (Community o Ultimate)
    • millor integració amb Spring Boot, Maven i Spring Initializr.
  • Alternativa: VS Code amb extensions recomanades:
    • Language Support for Java
    • Spring Boot Extension Pack
    • Lombok Annotations Support

2. Estructura del projecte (Maven / Spring Boot)​

El backend segueix una estructura estàndard Maven / Spring Boot:

backend/
├── pom.xml                                   # Configuració de Maven
├── src/
│   ├── main/
│   │   ├── java/com/example/ldp/
│   │   │   ├── LineDancePlatformApplication.java    # Classe principal Spring Boot
│   │   │   │
│   │   │   ├── domain/                              # ⭐ Entitats JPA (model de domini)
│   │   │   │   ├── Dance.java                       # Ball amb nivell, tags, timestamps
│   │   │   │   ├── Song.java                        # Cançó amb artista, any, ISRC
│   │   │   │   ├── Link.java                        # Enllaç multimèdia (YouTube, Spotify...)
│   │   │   │   ├── Level.java                       # Nivell (BEGINNER, INTERMEDIATE, ADVANCED, EXPERT...)
│   │   │   │   ├── LinkKind.java                    # Enum tipus d'enllaç
│   │   │   │   ├── Choreographer.java               # Coreògraf (Fase 2)
│   │   │   │   ├── Location.java                    # Lloc (Fase 2)
│   │   │   │   └── Venue.java                       # Sala / local (Fase 2)
│   │   │   │
│   │   │   ├── repository/                          # Repositoris JPA
│   │   │   ├── service/                             # Lògica de negoci
│   │   │   ├── web/                                 # Controladors REST
│   │   │   └── config/                              # Configuració (seguretat, CORS, etc.)
│   │   │
│   │   └── resources/
│   │       ├── application.yml                      # Configuració Spring Boot
│   │       └── db/migration/                        # Scripts Flyway
│   │           ├── V1__init_schema.sql
│   │           ├── V2__seed_levels.sql
│   │           └── ...
│   │
│   └── test/java/...                                # Tests (unitaris / d’integració)
│
└── target/                                          # Output de build generat per Maven

Les migracions de Flyway viuen a:

src/main/resources/db/migration

3. Base de dades PostgreSQL​

Pots fer servir PostgreSQL amb Docker (recomanat per local) o amb instal·lació directa.

3.1. Opció A – PostgreSQL amb Docker​

Exemple bàsic de docker-compose.yml (pots adaptar noms/ports):

services:
  ldp-postgres:
    image: postgres:16
    container_name: ldp-postgres
    environment:
      POSTGRES_DB: ldp
      POSTGRES_USER: ldp_user
      POSTGRES_PASSWORD: ldp_password
    ports:
      - "5432:5432"
    volumes:
      - ldp_pgdata:/var/lib/postgresql/data

volumes:
  ldp_pgdata:

Arrencar:

docker-compose up -d

3.2. Opció B – PostgreSQL instal·lat en local​

  • Crea una base de dades:
    • Nom: ldp
    • Usuari: ldp_user
    • Contrasenya: ldp_password
  • Comprova que:
    • el servei PostgreSQL està actiu,
    • escolta al port 5432 (o el que hagis definit).

4. Configuració de Spring Boot (profiles i datasource)​

4.1. Fitxers d’aplicació​

Normalment trobaràs:

  • application.yml – configuració comuna,
  • application-local.yml (o application-dev.yml) – configuració per desenvolupament local.

Exemple orientatiu de configuració de datasource:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/ldp
    username: ldp_user
    password: ldp_password
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    properties:
      hibernate.format_sql: true

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration

4.2. Perfil actiu​

Per treballar en local acostuma a utilitzar-se un perfil local o dev.

Exemples:

  • Variable d’entorn (Linux/macOS):

    export SPRING_PROFILES_ACTIVE=local

  • Variable d’entorn (Windows PowerShell):

    $env:SPRING_PROFILES_ACTIVE="local"

  • Paràmetre en arrencar l’aplicació amb Maven:

    mvn spring-boot:run -Dspring-boot.run.profiles=local

  • Paràmetre amb Gradle:

    ./gradlew bootRun --args='--spring.profiles.active=local'

5. Secrets i seguretat bàsica​

Per treballar en local cal definir alguns valors com:

  • JWT_SECRET – clau per signar els tokens JWT,
  • altres claus d’integracions externes (si n’hi ha).

Exemple amb variables d’entorn:

export JWT_SECRET="canvia_a_una_clau_llarga_per_dev"

Regles bàsiques:

  • no versionar mai secrets reals al repositori,
  • en producció: utilitzar variables d’entorn o un gestor de secrets.

La part conceptual de seguretat està descrita a:

  • architecture/security

6. Arrencar el backend en local​

6.1. Clonar i compilar​

Clona el repositori (exemple d’URL):

git clone https://github.com/your-org/line-dance-platform.git
cd line-dance-platform/backend

Compila:

mvn clean install
# o, si fas servir Gradle:
# ./gradlew clean build

6.2. Arrencar l’aplicació​

Amb Maven (perfil per defecte):

mvn spring-boot:run

Amb Maven + perfil local:

mvn spring-boot:run -Dspring-boot.run.profiles=local

Amb Gradle:

./gradlew bootRun

Amb Gradle + perfil local:

./gradlew bootRun --args='--spring.profiles.active=local'

Si tot va bé, a la consola veuràs alguna cosa com:

Started LineDancePlatformApplication in X.XXX seconds (JVM running for X.XXX)

Per defecte, el backend escolta a:

http://localhost:8080

(o el port que hagis configurat).

7. Provar que l’API respon​

7.1. Endpoint de salut (si n’hi ha)​

Exemple típic (Spring Actuator):

GET /actuator/health

Es pot provar amb:

curl http://localhost:8080/actuator/health

7.2. Endpoints de domini​

  • Si hi ha endpoints públics:
    • exemple: GET /api/dances
  • Si tot està protegit amb JWT:

    1. fes un POST /auth/login amb email i password,

    2. obtén l’accessToken,

    3. envia’l al header:

      Authorization: Bearer ACCESS_TOKEN_AQUI

Més detalls a:

  • architecture/security

8. Migracions i dades inicials​

Quan el backend arrenca amb Flyway activat:

  • s’apliquen automàticament totes les migracions de db/migration,
  • es creen taules, índexs i constraints.

Si hi ha dades de prova (seed):

  • poden estar en scripts del tipus Vx__seed_*.sql,
  • o en inicialitzadors Java (per exemple, CommandLineRunner).

Per canvis d’esquema i redissenys de model, consulta:

  • architecture/db-redesign-plan
  • history/changelog

9. Errors habituals (troubleshooting)​

Error: “Connection refused” a PostgreSQL​

Comprova:

  • que el contenidor Docker estigui actiu (docker ps), o
  • que el servei local de PostgreSQL estigui en execució.

Revisa:

  • host: localhost vs nom de contenidor,
  • port: 5432 (o el que hagis configurat).

Error: “Flyway validation failed”​

Significa que l’estat de la BD no coincideix amb els scripts actuals.

En entorn local, opcions:

  • esborrar la BD i deixar que Flyway la torni a crear,
  • revisar manualment quines migracions s’han aplicat i ajustar-les.

Error: “Failed to configure a DataSource”​

Revisa:

  • spring.datasource.url,
  • usuari i contrasenya de la DB,
  • que el driver de PostgreSQL estigui declarat al pom.xml (dependència postgresql).

10. Documents relacionats​

  • Visió i stack general:
    • overview/vision
    • overview/tech-stack
  • Arquitectura global:
    • architecture/architecture-overview
  • Seguretat:
    • architecture/security
  • Model de dades i migracions:
    • architecture/db-redesign-plan
  • Roadmap i backlog:
    • roadmap/roadmap-technical-details
    • roadmap/backlog