Skip to main content

Chapter 1: Getting Started with GitHub Codespaces

Objectives​

  • Set up a cloud development environment with GitHub Codespaces
  • Launch the e-contact-backend project
  • Understand the project structure
  • Perform initial API tests

🌐 What is GitHub Codespaces?​

GitHub Codespaces is a cloud development environment that allows you to:

  • Develop directly from the browser
  • Have a pre-configured environment
  • Avoid local installation issues
  • Collaborate easily
Main Advantage

No need to install Java, Maven, PostgreSQL, or any other tool on your machine!

Prerequisites​

  • GitHub account (free)
  • Modern web browser

Setup Steps​

Step 1: Access the Repository​

  1. Open the main repository:
Repository

URL: https://github.com/hrhouma1/inskillflow-docs-formation-spring-boot-projet-e-contact-backend

Step 2: Create a Codespace​

  1. Click on the green Code button
  2. Select the Codespaces tab
  3. Click on Create codespace on main
┌─────────────────────────────────────────┐
│  Code ▼                                 │
├─────────────────────────────────────────┤
│  Local    │  Codespaces               │
│           │                            │
│           │  ┌──────────────────────┐  │
│           │  │ + Create codespace   │  │
│           │  │   on main            │  │
│           │  └──────────────────────┘  │
└─────────────────────────────────────────┘

Step 3: Wait for Initialization​

The Codespace will:

  1. Create a virtual machine
  2. Clone the repository
  3. Install dependencies
  4. Open VS Code in the browser

⏱️ Estimated time: 2-3 minutes

Step 4: Verify the Environment​

Once the Codespace is ready, open the terminal and verify:

# Verify Java
java -version
# Expected: openjdk 17.x.x or higher

# Verify Maven
./mvnw -version
# Expected: Apache Maven 3.x.x

🏃 Launch the Application​

Start Command​

In the Codespace terminal:

./mvnw spring-boot:run

Expected Output​

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.2.x)

...
Started EContactApplication in X.XXX seconds

Access the Application​

When the application starts, Codespaces displays a notification:

┌──────────────────────────────────────────────────┐
│  Your application running on port 8080 is       │
│  available.                                      │
│                                                  │
│  [Open in Browser]  [Make Public]               │
└──────────────────────────────────────────────────┘

Click on Open in Browser to access the API.

🔍 Explore the Project Structure​

inskillflow-docs-formation-spring-boot-projet-e-contact-backend/
│
├── 📁 src/main/java/com/example/econtact/
│   │
│   ├── 📄 EContactApplication.java      # Entry point
│   │
│   ├── 📁 config/
│   │   ├── SecurityConfig.java          # Security configuration
│   │   └── CorsConfig.java              # CORS configuration
│   │
│   ├── 📁 controller/
│   │   ├── ContactController.java       # Public endpoint /api/contact
│   │   ├── AuthController.java          # Authentication endpoints
│   │   └── AdminController.java         # Protected admin endpoints
│   │
│   ├── 📁 model/
│   │   ├── Lead.java                    # Contact/Lead entity
│   │   ├── User.java                    # User entity
│   │   └── enums/                       # RequestType, LeadStatus, Role
│   │
│   ├── 📁 dto/
│   │   ├── ContactRequest.java          # Contact form DTO
│   │   ├── LoginRequest.java            # Authentication DTO
│   │   └── LeadResponse.java            # Lead response DTO
│   │
│   ├── 📁 repository/
│   │   ├── LeadRepository.java
│   │   └── UserRepository.java
│   │
│   ├── 📁 service/
│   │   ├── LeadService.java
│   │   ├── UserService.java
│   │   └── EmailService.java
│   │
│   └── 📁 security/
│       ├── JwtService.java              # JWT generation/validation
│       ├── JwtAuthenticationFilter.java # Authentication filter
│       └── UserDetailsServiceImpl.java
│
├── 📁 src/main/resources/
│   └── application.yml                   # Configuration
│
├── 📁 frontend/                          # Test frontend
│
├── 📁 troubleshooting/                   # Troubleshooting guides
│
└── 📁 cours/                             # Documentation and courses

Initial API Tests​

Test 1: Verify API Accessibility​

curl http://localhost:8080/api/health

Expected response:

{"status": "UP"}

Test 2: Submit a Contact (Public Endpoint)​

curl -X POST http://localhost:8080/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jean Dupont",
    "email": "jean.dupont@example.com",
    "company": "Ma Société",
    "phone": "514-555-1234",
    "requestType": "INFO",
    "message": "I would like more information about your services."
  }'

Expected response:

{
  "id": 1,
  "fullName": "Jean Dupont",
  "email": "jean.dupont@example.com",
  "status": "NEW",
  "createdAt": "2025-02-02T12:00:00"
}

Test 3: Access a Protected Endpoint (Without Token)​

curl http://localhost:8080/api/admin/leads

Expected response:

{
  "status": 401,
  "error": "Unauthorized"
}

⚠️ Common Issues​

Port 8080 Already in Use​

# Identify the process
lsof -i :8080

# Or use another port
./mvnw spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

Database Error​

Ensure the H2 configuration is active for development in application.yml.

Codespace Disconnecting​

Free Codespaces have a time limit. Restart if necessary.

Troubleshooting Resources​

For more details on steps and troubleshooting:

Detailed Guides

📖 Complete Troubleshooting Folder

Validation Checklist​

Before moving to the next chapter, ensure you have:

  • Successfully created a Codespace
  • Launched the Spring Boot application
  • Tested the /api/contact endpoint
  • Understood the project structure

⏭️ Next Step​

Chapter 2: Troubleshooting →

Back to module index