1.6.X

Developer Onboarding

This document walks a new developer through the process of onboarding to the Magma project.

Project overview

Magma is an open-source software platform that gives network operators an open, flexible, and extendable mobile core network solution. Our mission is to connect the world to a faster network by enabling service providers to build cost-effective and extensible carrier-grade networks.

In more approachable terms, Magma is a collection of software that makes running things like a cellular network affordable and customizable. With Magma's current rate of growth, increasing stability and reliability of the platform are all huge wins.

There are three main components in the Magma software platform: Access Gateway (AGW), Orchestrator (Orc8r), and Federation Gateway (FeG). If you want to read more, see the Magma intro docs.

Access Gateway

The AGW provides network services and policy enforcement. In an LTE network, the AGW implements an evolved packet core (EPC), and a combination of an AAA and a PGW. It works with existing, unmodified commercial radio hardware.

More generally, the AGW defines datapath rules for connecting subscribers through to the Internet. It pulls configuration from Orc8r, sets datapath rules, manages charging and accounting, reports state and metrics to Orc8r, and more.

Orchestrator

The Orc8r is a centralized controller for a set of networks. In SDN terms, Orc8r handles the control plane. This means one Orc8r serves many gateways -- pushing configuration to the gateways and pulling state and metrics from the gateways.

One of the functions of the Orc8r is to expose a management REST API. The REST API is defined as an OpenAPI specification (aka Swagger specification), and made available to operators over mutually-authenticated HTTPS. The Orc8r also exposes a series of gRPC services which gateways can call to report state, receive config updates, etc.

Federation Gateway

The FeG serves as the interface to existing operator cores, affording a modern, flexible interface on top of existing protocols and architectures.

Points of contact

Check out the Community page for community entry points. The principal resources are

  • GitHub Discussions page. Best place to ask questions if you're stuck or want more context.
  • Community Slack channel. Say hello in #general and let us know you're onboarding to the project.

Ramp-up resources

Briefly check out the resources below

Getting started

Set up development environment

Part of setting up the development environment involves updating your shell rc files. When we say "add to your shell rc file", if you don't know what that means, then add it to your ~/.bash_profile (or ~/.zshrc if you're using zsh).

Note: this guide assumes you have access to an IntelliJ Ultimate Edition license. The majority of the functionality should still work without the license. Also, plenty of Magma developers use VS Code, and a minority also use other IDEs.

Howto

  1. Import @hcgatewood's Google Chrome bookmarks: bookmarks-hcgatewood.html. These bookmarks provide a starting point for accessing resources across the Magma ecosystem.
  2. Add the following to your shell rc file, then restart your terminal
# MAGMA_ROOT denotes the root of the Magma repo
export MAGMA_ROOT=~/magma

# noti sends notification based on previous command success/fail
# Default sound is "default"
function noti() {
    if [[ $? = 0 ]] ; then
        title="✅" ; sound="ping"
    else
        title="❌" ; sound="basso"
    fi
    terminal-notifier -title "$title" -message "Finished at $(date +%X)" -sound "$sound"
}
  1. Install the Homebrew package manager
  2. Install terminal-notifier via brew install terminal-notifier
  3. Install IntelliJ Ultimate Edition via brew install --cask intellij-idea
  4. Import @hcgatewood's IntelliJ settings: intellij-hcgatewood.zip
  5. Clone the Magma repository via git clone git@github.com:magma/magma.git ${MAGMA_ROOT}

Install Magma locally

Install Magma locally and get everything running.

Howto

  1. Follow the prerequisites guide and install all development tools, up to but not including the "Build/Deploy Tooling" section
  2. (Optional) If you opt to use IntelliJ IDEA as your local IDE, follow the instructions in the Set up IntelliJ section below before you proceed
  3. Run all Orc8r tests
    1. Via Docker build script: cd ${MAGMA_ROOT}/orc8r/cloud/docker && ./build.py -t ; noti
    2. Via IntelliJ
  4. Follow the quick start guide to get an AGW and Orc8r instance running on your dev machine
  5. Visit the local Swagger UI view of our REST API (URL is in @hcgatewood's Google Chrome bookmarks) and list the set of managed networks -- there should be one named "test"

Note: remember to periodically call docker system prune to clear outdated Docker artifacts from your dev machine.

Set Up IntelliJ

We recommend using IntelliJ IDEA for general Magma development, or Visual Studio Code for a free alternative.

For IntelliJ IDEA, we provide a set of run configurations that support rapidly testing Magma code. See Testing Tips for more details.

To set up your local IntelliJ environment, perform the following

  1. After cloning the Magma repo, open the directory in IntelliJ
  2. Ensure the Go plugin has been installed by going to Preferences > Plugins > search for the plugin "Go"
  3. Specify the location of the Go SDK by going to Preferences > Languages & Frameworks > Go > GOROOT and selecting the relevant location
  4. Create a Go module for the project by going to Files > Project Structure > Project Settings > Modules > Click on "+" sign in the toolbar > New Module > Next. When you reach the new module creation page, enter the following information:
    • Module name: magma
    • Content root, module file location: full path to your local Magma clone, e.g. /Users/your_username/magma

After completing the above steps, restart your IDE and ensure the environment is properly set up

  1. Open "Project" on the left toolbar, and display "Project Files". All the files in the root magma directory should be displayed without a yellow background. This indicates IntelliJ recognizes the files as part of the module.
  2. At the top-right corner of your IDE, you should see a drop-down menu showing a list of run configurations for the Magma test suites, with a green triangular button that allows you to run the selected test. Alternatively, when you open your run configurations (Run > Edit Configurations), you should see something like the below

intellij_initial_run_configs

You can now run all (Orchestrator) tests in one click.

NOTE: a minority of tests require a running Postgres instance, and will otherwise fail with connection errors. You can use orc8r/cloud/docker/run.py to spin up the required test DB.

Complete a starter task

If you haven't already, join our community Slack channel via the link from the Community page and say hello in #general. We can point you toward a good starter task. You can also use the good first issue tag on our GitHub repo to search for good starter tasks.

As you're working on your starter task, refer to Development Workflow for guidance on how to author a pull request and Contributing Conventions for Magma conventions. Once your pull request is approved and merged, you're now an official contributor to the Magma project!

Next steps

The community Slack workspace is a great place to get connected. From there, we can coordinate choosing appropriate tasks given your skill set and the Magma roadmap.

As you get acquainted with the codebase, consider the following sources of documentation

  • Magma Docusaurus. This site! First stop for documentation.
  • doc.go files. Many Go packages have a doc.go file with a summary of the package's functionality.
  • Tests. Tests provide both testing and documentation of expected functionality.
← AlertsNext →