Skip to content

Installation & Setup

Jump to bottom
Splines edited this page Oct 17, 2024 · 26 revisions

Installing MaMpf on your server or locally

  • See the installation guide here. (Maybe outsource to the wiki?)
  • See the testing guide here. (This one has not been checked for some time and might be outdated).

Setting up your workspace (as a dev team member)

Prerequisites:

Yes, there are quite a few tools that you need. But once you've installed them, updates are only necessary once in a while, so it's just a pain in the beginning...

  • Have git installed.
  • Install a working Ruby environment. We recommend rbenv. With that ruby environment, you can then install a Ruby version as described in their Readme.
  • Install Bundler as Ruby package manager (these "packages"/libraries are called gems in Ruby).
  • Install Node.js in one of its latest versions (LTS). You need this locally for JavaScript linting (among others). Also install Yarn as Node.js package manager.
  • Install a recent Python version (>=3.8). This is only needed such that the VSCode Test explorer can execute a custom Python script to initiate unit tests inside the Docker Desktop environment.
  • Install Docker Desktop as our containerization tool. This is crucial for developing as you don't want to have to setup the database, the mail server, mampf itself etc. manually all the time.

Then MaMpf-specific:

  • Clone the MaMpf Git repo locally. If you're working on Windows, we highly recommend to use WSL (with Ubuntu 24 LTS). Make sure to run wsl --update in Powershell. For Windows users, you may also like the Windows Terminal
  • Optional: Install the recommended workspace extensions in VSCode. We highly recommend VSCode as editor. Many settings and convenience features are already pre-populated for you to ease onboarding and working with VSCode and multiple team members use it.
  • Install the Node.js packages with yarn: yarn install
  • Install Ruby gems: bundle install
  • There are many commands that you use frequently. We make them easily accessible via the just command line runner. To install it, see the section below.

To finally start MaMpf locally:

  • Make sure you've started Docker Desktop.
  • Run just docker up -d
  • Wait a bit, then access http://localhost:3000/. You should see the MaMpf login screen 🎉
  • In order to login, you need actual users in the database. We have some initial data available with users, and lectures, homework assignments etc. Preseed the database via just docker up-reseed -d.

To continue: Get to know more about how we structure code, how to lint Ruby, JavaScript etc. files and how we work by checking out the other Wiki pages. Don't hesitate to ask a team member if you're stuck; it happens to all of us.

Installation of just (command-line runner)

just is an amazing command line runner that we employ to document frequently-used commands and make them available at your fingertips. To install just, follow these steps:

Do not install just via apt or another package manager as the version there might be outdated; and we may make use of features that require the most up-to-date version.

  • Make sure you have a LTS-version of Node.js installed.
  • Go the directory where you cloned the mampf repository and where the package.json is located.
  • Run yarn just-install (the commands that will run can be seen in the package.json file).
  • Reload your current shell (e.g. close and open it again). Type just --version and it should give the version of just.
  • Finally, use just by executing just in your shell and you will see available commands with comments explaining what they do.

If you want to update just later on, run yarn just-update.

Clone this wiki locally