1. Overview#

StudentHub is a platform for corporate recruitment and trainee management. It consists of a single Yii2 backend and four Ionic Angular frontends: candidate, company, staff, and admin. This Quickstart guides you through running all components locally for development purposes.

2. Prerequisites#

• OS: macOS, Linux, or Windows (with WSL2)
• Required tools:
  • Git
  • Docker and Docker Compose
  • Node.js (v14+ recommended for Ionic apps)
  • npm (v6+ recommended) or yarn (check each frontend's README)
  • For direct backend development (not via Docker): PHP 7.4+ with exif and pdo_mysql extensions
  • (Optional) Composer if you plan to run PHP commands outside Docker
  • (Optional) Puppeteer (Node.js 12+ and global install) for backend features that require headless browser automation

See the backend setup guide for more details.

3. Clone the Repositories#

Clone the main backend and the four frontend repositories. For convenience, place all repos in a single parent directory:

mkdir studenthub-dev && cd studenthub-dev

# Backend
git clone https://github.com/BAWES-Universe/studenthub.git

# Frontends
git clone https://github.com/BAWES-Universe/studenthub-admin.git
git clone https://github.com/BAWES-Universe/studenthub-company.git
git clone https://github.com/BAWES-Universe/studenthub-staff.git
git clone https://github.com/BAWES-Universe/studenthub-candidate.git

The backend provides all API endpoints. Each frontend is a separate Ionic Angular app that connects to the backend.

4. Environment Configuration#

Backend#

The backend uses environment-specific configuration under the environments/ directory. To initialize the backend for development, run the Yii2 init script:

cd studenthub
php init --env=Development --overwrite=n

This copies the appropriate config files for development and sets up writable directories and cookie validation keys.
If you need to customize environment variables (database, cache, email, etc.), edit the generated config files in environments/dev/common/config/ and related locations.
Do not commit secrets. Use placeholder values such as:

'db' => [
    'dsn' => 'mysql:host=mysql;dbname=studenthub',
    'username' => 'studenthubuser',
    'password' => 'yourpassword',
],
'mailer' => [
    'useFileTransport' => true, // emails are saved to files in dev
],

See environments/index.php for details on environment-specific files.

Frontends#

Each frontend uses src/environments/environment.ts for environment-specific settings. You will need to update the apiEndpoint property to point to your local backend (see section 6).

5. Running the Backend#

From the studenthub directory, start the backend and its dependencies using Docker Compose:

docker-compose -f docker-compose-dev.yml -p studenthub-dev-server up -d

This starts the backend, MySQL, and Redis containers.
To access the backend container shell:

docker-compose exec backend bash

Database migrations:
Inside the backend container, run:

./yii migrate

Flush cache (if needed):

./yii cache/flush-schema db
./yii cache/flush cache

Default API endpoints:

• Admin: http://localhost:21080
• Candidate: http://localhost:22080
• Company: http://localhost:23080
• Staff: http://localhost:25080
• Inspector: http://localhost:24080
• Verification: http://localhost:26080

See docs/api-endpoints.md for more.

For more backend setup details, see docs/setup.md.

6. Running the Frontends#

For each frontend (admin, candidate, company, staff):

1. Install dependencies:

   ⧉

   cd studenthub-<frontend>
   npm install
   

2. Configure API endpoint:

   Edit src/environments/environment.ts and set the apiEndpoint to the local backend URL. For example:

   • Admin: apiEndpoint: 'http://localhost:21080/v1'
   • Candidate: apiEndpoint: 'http://localhost:22080/v1'
   • Company: apiEndpoint: 'http://localhost:23080/v1'
   • Staff: apiEndpoint: 'http://localhost:25080/v1'

   (The /v1 path is typical for API routes; check api-endpoints.md for specifics.)

3. Run in development mode:

   ⧉

   npm start
   # or
   ionic serve
   

   By default, the app runs on http://localhost:8100 (Ionic) or http://localhost:3000 (if using Docker for the frontend).
   See each frontend's README or package.json for custom scripts or port overrides.

7. Sanity Checks#

• Visit the backend API endpoints (e.g., http://localhost:21080) in your browser; you should see a response or API documentation.
• Start the candidate app and ensure it loads in the browser.
• Attempt to log in or access the dashboard in any frontend to verify end-to-end connectivity.
• Use the backend healthcheck or code generator if available.

8. Troubleshooting#

• Port conflicts:
  If Docker or Ionic reports a port is in use, stop other services or change the port in the relevant config.
• Missing environment variables:
  Ensure you have run the Yii2 init script and updated all required config files.
• Database or migration errors:
  Access the backend container and run ./yii migrate. If you see schema errors, flush the cache as shown above.
• WSL2 quirks:
  No specific issues are documented, but general Docker/WSL2 advice applies.
• Frontend not connecting to backend:
  Double-check the apiEndpoint in each frontend's environment.ts and ensure the backend is running on the expected port.

For more troubleshooting and advanced configuration, see:

• docs/setup.md
• docs/api-endpoints.md
• docs/user-roles.md

Note:
If you encounter issues not covered here, consult the README and documentation in each repo, or check the package.json for available scripts and commands.