FlexRoster

FlexRoster is a comprehensive full-stack application designed to manage flex schedules for high school students. Developed with a focus on flexibility and efficiency, this application allows students to request attendance in different classes during their designated flex period. Built as a monorepo, FlexRoster encompasses multiple apps and shared packages to cater to various roles including students, teachers, and administrators.

Key Features

• Role-Based Views: Customized UIs for students, teachers, and other roles.
• Modular Architecture: Built as a monorepo with multiple apps and shared packages.
• TypeScript Throughout: Frontend and backend fully implemented in TypeScript for type safety and developer experience.
• Next.js Client: Utilizing the power and flexibility of Next.js for the frontend.
• ElysiaJS and Bun.js: A fast backend setup using ElysiaJS on the Bun.js runtime, optimized for Docker Swarm environments.
• AuthJS with Azure SAML: Streamlined authentication integrated with school's Active Directory.
• Dockerized PostgreSQL and Redis: Robust database management with Drizzle ORM and efficient caching/logging with Redis.
• Eden and Socketi: Facilitating real-time communication and data exchange across services.
• OneRoster API Integration: Ensures up-to-date class rosters and seamless data synchronization.
• GO Cli and Automation: Included CLI tool for easy setup and configuration, as well as automation scripts for syncing flexroster.

TODO

• Create choco package for Windows
• ReWrite Server in Go
• Add Kubernetes Support
• Mobile App
• Support sqlite3
• Support for multiple cloud providers

Getting Started

Prerequisites

• OneRoster API credentials from Infinite Campus
• Azure AD application with SAML integration
• Cloud vps or on prem server with Docker

Configuration

Install the CLI Tool not required but recommended by going to the releases page and downloading the latest release for your platform.

Homebrew

brew install biohackerellie/tap/flexroster

Manual Install

curl -L -o flexroster.tar.gz https://github.com/biohackerellie/FlexRoster/releases/download/<latest-release>/flexroster_<latest-release>_<platform>.tar.gz && tar -C /usr/local/bin -xvf flexroster.tar.gz

Initializing your config

After you've installed the CLI tool, cd into the directory where you want to store your configuration files, including your docker-compose.yml and .env files, and run the following command:

Windows

# You will have to run the CLI exe directly from the terminal or you can add the path to the exe to your PATH variable
# Once we have a winget and chocolatey package this will be done automatically

.\flexroster.exe init # without the .exe location added to path

flexroster init # with the .exe location added to path

Linux/MacOS

flexroster init

This command will walk you through all the required steps to configure your environment. If you don't have all the needed info at the time of running the command, you can always edit the generated config files later.

Config File

The Config file provides mutable variables to the CLI such as preferred names or admin users.The config.yaml file's default location for windows and poisx systems is in the user's config directory at $HOME/.config/flexroster/config.yaml but you can use a -cfg flag to specify a different location.

Env File

The .env file is used to store environment varialbes for the docker containers. This file will be automatically generated by the CLI tool after the initial setup.

Deployment

Once you have your configuration files set up, create your docker-compose.yml file:

services:
  server:
    image: ghcr.io/biohackerellie/flexserver:main
    ports:
      - "3030:3030"
    deploy:
      restart_policy:
        condition: on-failure
    networks:
      - webnet
    env_file:
      - .env

  client:
    image: ghcr.io/biohackerellie/flexclient:main
    ports:
      - "3000:3000"
    deploy:
      restart_policy:
        condition: on-failure
    networks:
      - webnet
    env_file:
      - .env

networks:
  webnet:

And then run:

docker-compose up -d

CLI Usage and Cron Jobs

To get a full list of all the commands the CLI has, you can run

flexroster -h # outputs all base commands and flags

which outputs the following:

Usage:
  flex [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Edit flexroster configuration
  help        Help about any command
  init        Initialize FlexRoster configuration
  script      Run maintenance scripts
  version     Print the version of the flexroster CLI

Flags:
      --cfg string   path to config file (default is $HOME/.config/flexroster/config.yaml)
  -h, --help         help for flex
  -t, --toggle       Help message for toggle

# or if you need flags for a specific command
flexroster <command> -h

The script command is used to run regular maintenance commands such as flushing logs and resyncing the OneRoster API to FlexRoster's database. You can run this command manually or set up a cron job to run the command at regular intervals.

30 0 * * * flexroster --cfg /path/to/config.yaml script --n # runs the nightly script at 12:30 am every day to resync the rosters