Installation & Setup

Installing MaMpf on your server or locally

The following two guides are likely to be outdated. Instead, start with the section below if you're a new team member.

• 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. Read each bullet point to the end, then follow the commands. Proceed with every bullet point. This way you don't miss any important information.

When new tools are installed and command are "not found", you'll probably have to just re-open your terminal such that new configurations are loaded. If you encounter issues like build errors, there's probably some underlying ...-dev Linux package missing. Via a quick search on the Internet, you will probably find out which one to install.

• 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. Make sure to install the same version as is specified at the top of our Gemfile.
• Install Bundler as Ruby package manager (these "packages"/libraries are called gems in Ruby). E.g. do gem install bundler.
• Install Node.js (one of its latest versions (LTS)). nvm is a popular way to manage your Node.js versions. Install it as described here and don't forget to actually install Node.js afterwards as described here. Alternatively, just go to here, select linux and nvm, and it will show you the instructions. You need Node.js 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. Make sure to also include the pdfcomprezzor submodule by using git clone --recurse-submodules. If you've already cloned the repo without the --recurse-submodules flag, run git submodule update --init --recursive.
  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. Some gems might install using native extension. If you encounter an error during the installation of pg, you probably need to install sudo apt install libpq-dev first.
• 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 (or just docker up-logs).
• Wait a bit, then access http://localhost:3000/. You should see the MaMpf login screen 🎉 The first time, it takes a while before all HTML files are completely rendered by Ruby on Rails. Also note that you might get an error screen showing "Migrations pending". These are database migrations. Just click on the button in the browser to perform the migrations. If this doesn't work, make sure to check the next bullet point (preseeding the database).
• In order to login, you need actual users in the database. We have some initial data available with users, lectures, homework assignments etc. Preseed the database via just docker up-reseed -d.

When images are pulled, you can safely ignore the message "Pull accessed denied for mampf, repository does not exist...".

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.