docs: add end-to-end tutorial (#384)

Signed-off-by: Guillaume Belanger <[email protected]>

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,54 @@
+name: Bug Report
+description: File an enhancement proposal
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thanks for taking the time to fill out this bug report! Before submitting your issue, please make
+        sure there isn't already a prior issue concerning this. If there is, please join that discussion instead.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: >
+        Describe the bug in detail. Include what you are experiencing.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: >
+        Include any relevant information about your environment. For example:
+          - Ella Core version: 1.2.1
+          - OS: Ubuntu 24.04
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction Steps
+      description: >
+        Provide a step-by-step guide to reproduce the bug.
+        For example:
+          1. Go to '...'
+          2. Click on '....'
+          3. Scroll down to '....'
+          4. See error
+    validations:
+        required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: >
+        Describe what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: shell

.github/workflows/integration-tests.yaml

@@ -75,13 +75,5 @@ jobs:
 
       - name: Run integration tests
         run: |
-          kubectl create ns dev2
           pip install tox
           tox -e integration
-
-      - name: Show logs
-        if: always()
-        run: |
-          kubectl logs -n dev2 -l app=router --tail=-1
-          kubectl logs -n dev2 -l app=ella --tail=-1
-          kubectl logs -n dev2 -l app=gnbsim --tail=-1

CONTRIBUTING.md

@@ -41,35 +41,54 @@ Build the image and push it to the local registry
 
 ```shell
 rockcraft pack
-sudo rockcraft.skopeo --insecure-policy copy oci-archive:$(ROCK_FILE) docker-daemon:$(OCI_IMAGE_NAME)
+sudo rockcraft.skopeo --insecure-policy copy oci-archive:ella-core_v0.0.5_amd64.rock docker-daemon:ella-core:latest
 docker tag ella-core:latest localhost:5000/ella-core:latest
 docker push localhost:5000/ella-core:latest
 ```
 
 Run End-to-End tests
 
 ```shell
-kubectl create ns dev2
 pip install tox
 tox -e integration
 ```
 
 ## How-to Guides
 
-### Build Backend
+### Build the Frontend
+
+Install pre-requisites:
 
 ```shell
-go build cmd/core/main.go
+sudo snap install node --channel=20/stable --classic
 ```
 
-### Build Frontend
-
 ```shell
-cd ui
-npm install
+npm install --prefix ui
 npm run build --prefix ui
 ```
 
+### Build the Backend
+
+Install pre-requisites:
+
+```shell
+sudo apt install clang llvm gcc-multilib libbpf-dev
+sudo snap install go --channel=1.23/stable --classic
+```
+
+Generate the eBPF Go bindings:
+
+```shell
+go generate ./...
+```
+
+Build the backend:
+
+```shell
+go build cmd/core/main.go
+```
+
 ### Build documentation
 
 ```shell

cmd/core/main.go

@@ -4,6 +4,7 @@ package main
 
 import (
 	"flag"
+	"fmt"
 	"log"
 	"os"
 
@@ -47,9 +48,9 @@ func startNetwork(dbInstance *db.Database, cfg config.Config) error {
 		return err
 	}
 
-	err = upf.Start(cfg.Interfaces.N3.Address, cfg.Interfaces.N3.Name, cfg.Interfaces.N6.Name)
+	err = upf.Start(cfg.Interfaces.N3.Address, cfg.Interfaces.N3.Name, cfg.Interfaces.N6.Name, cfg.XDP.AttachMode)
 	if err != nil {
-		return err
+		return fmt.Errorf("failed to start UPF: %v", err)
 	}
 	return nil
 }

core.yaml

@@ -1,4 +1,4 @@
-log-level: "debug"
+log-level: "info"
 db:
   path: "core.db"
 interfaces:
@@ -17,3 +17,5 @@ interfaces:
     tls:
       cert: "cert.pem"
       key: "key.pem"
+xdp:
+  attach-mode: "native"

docs/explanation/architecture.md

@@ -2,11 +2,45 @@
 description: Architecture explanation - Combining a 5G core network into a Single Binary.
 ---
 
-# Architecture - Combining 5G Network Functions into a Single Binary
+# The Ella Core Architecture Explained
 
-## The problem with typical 5G networks
+## What is a 5G Network?
 
-In a typical 5G network, the architecture is designed around a set of specialized components, collectively known as network functions (NFs). Each Network Function serves a specific role. Examples of key 5G network functions include:
+A 5G network represents the fifth generation of wireless technology. It brings fast data speeds, reliable low-latency communications, connectivity for IoT devices. 
+
+<figure markdown="span">
+  ![5G Network](../images/what_is_5g.svg){ width="700" }
+  <figcaption>5G Overview</figcaption>
+</figure>
+
+
+### Components of a 5G Network
+
+A 5G network is broadly divided into two major components: the Core Network and the Radio Access Network (RAN).
+
+#### 1. Core Network
+
+The 5G Core is the heart of a 5G network. It is designed to manage all data and signaling flows within the network. 
+
+Key Functions of the 5G Core:
+
+- **Authentication and Security**: Ensures that devices and users are authenticated and data transmission is secure.
+- **Session Management**: Establishes and maintains user sessions to provide stable data and voice communication.
+- **Policy**: Implements quality of service (QoS) rules.
+- **Data Network Access**: Connects user devices to external data networks like the internet or private networks.
+
+#### 2. Radio Access Network (RAN)
+
+The Radio Access Network (RAN) is the interface between user devices and the core network. It is responsible for transmitting and receiving signals over the air, enabling connectivity between the device and the Core.
+
+Key Components of the RAN
+
+- **gNB (Next Generation Node B)**: The 5G base station that connects user equipment (UE) to the core network.
+- **Antennas and Spectrum**: Handles communication over radio frequencies. 5G uses a range of spectrum bands, including low-band, mid-band, and high-band (millimeter wave).
+
+## The problem with typical 5G Core Networks
+
+Typical 5G Core networks are designed around a set of specialized components, collectively known as network functions (NFs). Each Network Function serves a specific role. Examples of key 5G network functions include:
 
 - **Access and Mobility Management Function (AMF)**: Handles registration, connection, and mobility management for user devices.
 - **Session Management Function (SMF)**: Manages session lifecycle and assigns IP addresses to devices.
@@ -23,7 +57,7 @@ These Network Functions are typically deployed as separate microservices, levera
 
 ## The Ella Core approach
 
-Ella Core was designed with the specific needs of private mobile networks in mind. For these users, simplicity, reliability, and security are what counts most. To address these requirements, we made a conscious decision to combine all 5G network functions into a single binary.
+Ella Core was designed with the specific needs of private mobile networks in mind. For these users, simplicity, reliability, and security are what counts most. To address these requirements, we made the conscious decision to combine all 5G network functions into a single application.
 
 Users only interact with Ella Core through a web-based user interface or a REST API, both of which are built into the application.
 
@@ -36,6 +70,8 @@ Users only interact with Ella Core through a web-based user interface or a REST
 
 Ella Core still performs the same functions as traditional 5G networks, and behind the scenes, it implements the same 3GPP standards and protocols. However, HTTP communication between Network Functions is replaced with in-process function calls.
 
+This design greatly simplifies the deployment and operation of the Core network, as there is no need to manage multiple services, databases, or network connections.
+
 ### The database is embedded
 
 Persistent data is stored in an embedded database, eliminating the need for managing external databases. This design choice allows for a simple deployment process, backup and restore functionality, and (soon to be implemented) high availability features.

docs/explanation/subscriber_authentication.md

@@ -7,6 +7,7 @@ description: Explanation of subscriber authentication - IMSI, Ki, OP, OPc, and S
 ## Overview
 
 Subscriber authentication in 5G networks can be based on one of the following mechanisms:
+
 - 5G-AKA
 - EAP-AKA
 

docs/how_to/deploy.md

@@ -4,15 +4,12 @@ description: Step-by-step instructions to deploy Ella Core.
 
 # Deploy
 
-Ella Core is available as a Snap and a OCI container image.
+Ella Core is available as a Snap and a container image.
 
 === "Snap (Recommended)"
 
     Ella Core is available as a strictly confined Snap.
 
-    !!! note
-        The Snap package is currently under review from the Snap store team. In the meantime, you can install it using the `--devmode` flag.
-
     ## Pre-requisites
 
     - A machine with:
@@ -29,15 +26,15 @@ Ella Core is available as a Snap and a OCI container image.
     Install the snap:
 
     ```bash
-    sudo snap install ella-core --channel=edge --devmode
+    sudo snap install ella-core --channel=beta
     ```
 
     Connect the snap to the required interfaces:
 
     ```bash
     sudo snap connect ella-core:network-control
     sudo snap connect ella-core:process-control
-    sudo snap connect ella-core:bpf
+    sudo snap connect ella-core:sys-fs-bpf-upf-pipeline
     sudo snap connect ella-core:system-observe
     ```
 
@@ -73,7 +70,7 @@ Ella Core is available as a Snap and a OCI container image.
     Navigate to `https://localhost:5002` to access the Ella UI.
 
 
-=== "OCI Container Image"
+=== "Container"
 
     We provide a container image for Ella Core on GitHub Container Registry.
 
@@ -88,3 +85,56 @@ Ella Core is available as a Snap and a OCI container image.
     !!! note
         We are planning on publishing a Juju Kubernetes charm in the future. 
         This charm will allow you to operate Ella Core on Kubernetes.
+
+=== "Source"
+
+    You can build Ella Core from source.
+
+    !!! warning
+        Building from source is unsupported and may not work as expected.
+
+    ## Pre-requisites
+
+    Install the pre-requisites:
+
+    ```shell
+    sudo snap install go --channel=1.23/stable --classic
+    sudo snap install node --channel=20/stable --classic
+    sudo apt install build-essential
+    ```
+
+    Clone the Ella Core repository:
+
+    ```shell
+    git clone https://github.com/ellanetworks/core.git
+    ```
+
+    Move to the repository directory:
+
+    ```shell
+    cd core
+    ```
+
+    !!! note
+        If you want to build a specific version, checkout the tag after cloning the repository.
+        For example, to build version 0.0.4, run `git checkout v0.0.4`.
+
+    Build the frontend:
+    ```shell
+    npm install --prefix ui
+    npm run build --prefix ui
+    ```
+
+    Build the backend:
+    ```shell
+    go build cmd/core/main.go
+    ```
+
+    Edit the configuration file at `core.yaml` to configure the network interfaces.
+
+    Start the service:
+    ```shell
+    ./main --config core.yaml
+    ```
+
+    Navigate to `https://localhost:5002` to access the Ella UI.

docs/reference/config_file.md

@@ -29,6 +29,8 @@ Start Ella core with the `--config` flag to specify the path to the configuratio
     - `tls` (object): The TLS configuration.
       - `cert` (string): The path to the TLS certificate file.
       - `key` (string): The path to the TLS key file.
+- `xdp` (object): The XDP configuration.
+  - `attach-mode` (string): The XDP attach mode. Options are `native` and `generic`. `native` is the most performant option and only works on supported drivers.
 
 ## Example
 
@@ -52,4 +54,6 @@ interfaces:
     tls:
       cert: "/etc/ssl/certs/core.crt"
       key: "/etc/ssl/private/core.key"
+xdp:
+  attach-mode: "native"
 ```