Getting Started with Effective Office

Getting Started with Effective Office

This guide will help you set up and run the Effective Office project for local development.

Table of Contents

• Project Overview
• Prerequisites
• Setting Up the Environment
  • Clone the Repository
  • Install Git Hooks
  • Configure Environment Variables
  • Set Up Credentials
• Running the Backend
  • Using Docker (Recommended)
  • Running Locally without Docker
• Running the Client Applications
  • Tablet Application (Compose Multiplatform)
  • iOS Tablet App
• Verifying the Setup
• Troubleshooting
• Development Workflow
• Additional Resources

Project Overview

Effective Office is a multi-module Kotlin application aimed at automating office processes and providing statistics for employees. The project follows a client-server architecture with a Spring Boot backend, multiple client applications including an iOS tablet app, and Docker-based containerization for deployment.

Key features include:

• Meeting room booking and management
• Real-time availability displays
• Google Calendar integration
• Office space visualization

Prerequisites

General Requirements

• Git
• JDK 17 or higher
• Gradle 8.0 or newer
• Docker and Docker Compose (optional, for containerized setup)

Backend Development

• PostgreSQL (if running without Docker)

Client Development

• Android Studio Meerkat or IntelliJ IDEA 2025 or newer
• Android SDK
• Xcode 16 or newer (for iOS development)
• CocoaPods (for iOS development)

Setting Up the Environment

Clone the Repository

git clone https://github.com/effective-dev-opensource/Effective-Office
cd Effective-Office

Install Git Hooks

./scripts/install.sh

This script installs a pre-commit hook that scans for potential secrets using Gitleaks.

Configure Environment Variables

Backend Environment Variables

cp backend/app/src/main/resources/env.example backend/app/src/main/resources/.env

Edit the .env file with your configuration:

SPRING_DATASOURCE_URL=jdbc:postgresql://0.0.0.0:5432/effectiveoffice
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=postgres

MIGRATIONS_ENABLE=true
APPLICATION_URL=http://localhost:8080
LOG_LEVEL=debug

CALENDAR_APPLICATION_NAME=YourApplicationName
CALENDAR_DELEGATED_USER=yourdelegateduseremail
GOOGLE_CREDENTIALS_FILE=classpath:google-credentials.json

DEFAULT_APP_EMAIL=yourdefaultappemail
FIREBASE_CREDENTIALS=classpath:firebase-credentials.json
DEFAULT_CALENDAR=yourdefaultcalendar

Deployment Environment Variables

cp deploy/dev/.env.example deploy/dev/.env

Edit the .env file with your configuration:

POSTGRES_DB=effectiveoffice
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/effectiveoffice

# Application Configuration
MIGRATIONS_ENABLE=true
LOG_LEVEL=DEBUG

CALENDAR_APPLICATION_NAME=EffectiveOffice
DEFAULT_CALENDAR=primary
TEST_CALENDARS=your_test_calendars
TEST_APPLICATION_URL=http://localhost:8080

LABEL=dev.effectiveoffice.local

Set Up Credentials

Google Calendar Credentials

To use Google Calendar API integration, you need to set up Google API credentials:

1. Create a project in the Google Cloud Console:

   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the Google Calendar API for your project

2. Create a service account:

   • Go to "IAM & Admin" > "Service Accounts"
   • Click "Create Service Account"
   • Enter a name and description for the service account
   • Grant the service account the necessary permissions (Calendar API roles)
   • Click "Create"

3. Generate a JSON key:

   • Select the service account you just created
   • Go to the "Keys" tab
   • Click "Add Key" > "Create new key"
   • Select "JSON" as the key type
   • Click "Create"
   • The JSON key file will be downloaded to your computer

4. Place the credentials file in the project:

   • Rename the downloaded file to google-credentials.json
   • Place it in backend/app/src/main/resources/

Firebase Credentials

For Firebase Cloud Messaging (FCM) integration, you need Firebase credentials:

1. Create a Firebase project:

   • Go to the Firebase Console
   • Create a new project or select an existing one

2. Generate a service account key:

   • Go to Project Settings > Service Accounts
   • Click "Generate new private key"
   • The JSON key file will be downloaded to your computer

3. Place the credentials file in the project:

   • Rename the downloaded file to firebase-credentials.json
   • Place it in backend/app/src/main/resources/

Android Keystore Files

For signing Android applications, you need keystore files:

1. Debug Keystore:

   • For development and testing, create a debug keystore:

     mkdir -p keystore
     keytool -genkey -v -keystore keystore/debug.keystore -alias androiddebugkey -storepass android -keypass android -keyalg RSA -keysize 2048 -validity 10000 -dname "CN=Android Debug,O=Android,C=US"

2. Production Keystore:

   • For production releases, create a secure keystore:

     mkdir -p keystore
     keytool -genkey -v -keystore keystore/main.keystore -alias release -keyalg RSA -keysize 2048 -validity 10000

   • Follow the prompts to enter your details and set a secure password

Running the Backend

Using Docker (Recommended)

1. Navigate to the deployment directory:

cd deploy/dev

2. Start the Docker containers:

docker-compose up -d

3. Check if the containers are running:

docker ps

4. View logs (optional):

docker logs effective-office-app-dev -f

Running Locally without Docker

1. Start a PostgreSQL container using Docker:

docker run --name postgres-effectiveoffice -e POSTGRES_DB=effectiveoffice -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:15-alpine

2. Build and run the backend application with the local profile:

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

This command:

• Builds and runs the backend application
• Activates the local Spring profile
• Uses the configuration from application-local.yml
• Connects to your local PostgreSQL database

The backend will be available at http://localhost:8080.

Running the Client Applications

Tablet Application (Compose Multiplatform)

Setup

1. Open the project in Android Studio or IntelliJ IDEA
2. Sync the Gradle project to download dependencies

Running on Android

1. Select an Android device or emulator

2. Run the composeApp configuration from Android Studio

   Or use Gradle:

   ./gradlew :clients:tablet:composeApp:installDebug

Running on iOS

1. Install CocoaPods dependencies and generate the Xcode project:

   ./gradlew :clients:tablet:composeApp:podInstall

2. Open the generated Xcode project:

   open clients/tablet/composeApp/build/xcode-frameworks/ComposeApp.xcodeproj

3. Select an iOS device or simulator in Xcode

4. Run the project in Xcode

iOS Tablet App

1. Open the Xcode project:

   open iosApp/iosApp.xcodeproj

2. Select a target device or simulator

3. Build and run the application

Verifying the Setup

Backend Verification

1. Open a web browser and navigate to http://localhost:8080/api/actuator/health
2. You should see a JSON response indicating the application is "UP"
3. API documentation is available at http://localhost:8080/api/swagger-ui.html

Client Verification

1. The tablet application should connect to the backend automatically if it's running
2. Check the application logs for any connection errors

Troubleshooting

Common Backend Issues

1. Database Connection Issues

   • Verify PostgreSQL is running: docker ps | grep postgres
   • Check database credentials in the .env file
   • Ensure the database port is not in use by another application

2. Application Fails to Start

   • Check the application logs: docker logs effective-office-app-dev
   • Verify all required environment variables are set
   • Ensure JDK 17 or higher is installed: java -version

3. API Endpoints Not Accessible

   • Check if the application is running: curl http://localhost:8080/api/actuator/health
   • Verify network settings and firewall configurations

4. Google Calendar API Issues

   • Verify that your credentials file is correctly formatted and has the necessary permissions
   • Ensure the Google Calendar API is enabled in your Google Cloud project
   • Check that the service account has the correct permissions

5. Firebase Notification Issues

   • Verify that your Firebase credentials are correct
   • Ensure the Firebase project has Cloud Messaging enabled
   • Check that the service account has the necessary permissions

Common Client Issues

1. Build Failures

   • Sync Gradle project and update dependencies
   • Check for compatibility issues between Gradle, Kotlin, and Android plugin versions
   • Clear build cache: ./gradlew clean

2. iOS Build Issues

   • Update CocoaPods: pod repo update
   • Reinstall pods: ./gradlew :clients:tablet:composeApp:podInstall --refresh-dependencies
   • Check Xcode version compatibility

3. Connection to Backend Fails

   • Verify the backend is running and accessible
   • Check API endpoint configuration in the client application
   • Ensure network permissions are granted to the application

Development Workflow

1. Start the backend server
2. Run the client application
3. Make changes to the code
4. Rebuild and restart as needed

For more information on the development workflow, including branching strategy and coding standards, please refer to the Development Guide.

Additional Resources

• Backend Documentation
• Client Documentation
• Build Logic Documentation
• Calendar Integration Documentation
• Development Guide