diff --git a/docusaurus/docusaurus.config.js b/docusaurus/docusaurus.config.js index 620eb36..2dadcd0 100644 --- a/docusaurus/docusaurus.config.js +++ b/docusaurus/docusaurus.config.js @@ -70,6 +70,7 @@ const config = { theme: { customCss: './src/css/custom.css', }, + blog: false, }), ], ], diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 7b5cef1..81625fd 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -11,23 +11,10 @@ // @ts-check -/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ -const sidebars = { - // By default, Docusaurus generates a sidebar from the docs folder structure - versionSidebar: [{type: 'autogenerated', dirName: '.'}], +import sidebarData from './sidebars.json'; - // But you can create a sidebar manually - /* - tutorialSidebar: [ - 'intro', - 'hello', - { - type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], - }, - ], - */ +const sidebars = { + docs: sidebarData.docs }; export default sidebars; diff --git a/docusaurus/sidebars.json b/docusaurus/sidebars.json index 21fc45f..d705a91 100644 --- a/docusaurus/sidebars.json +++ b/docusaurus/sidebars.json @@ -1,428 +1,501 @@ { - "docs": { - "Getting Started": [ - "basics/introduction", - "basics/prerequisites", - "basics/quick_start_guide", - "bazel/agw_with_bazel" - ], - "Tutorials": [ - { - "type": "subcategory", - "label": "Operate your own private mobile network with Charmed Magma", - "ids": [ - "tutorials/00_overview", - "tutorials/01_getting_started", - "tutorials/02_deploying_magma_orchestrator", - "tutorials/03_deploying_magma_agw", - "tutorials/04_integrating_agw_with_orc8r", - "tutorials/05_deploying_the_radio_simulator", - "tutorials/06_simulating_user_traffic", - "tutorials/06_destroying_the_env" - ] - } - ], - "Usage": [ - { - "type": "subcategory", - "label": "How-To", - "ids": [ - "howtos/ue_metering", - "howtos/config_agw_bridged", - "howtos/5g_nsa_support", - "howtos/call_tracing", - "howtos/events_monitoring", - "howtos/ipv6_agw", - "howtos/he_api", - "howtos/inbound_roaming", - "howtos/l3_transport", - "howtos/network_probe", - "howtos/package" - ] + "docs": [ + { + "type": "doc", + "id": "basics/introduction", + "label": "Introduction" + }, + { + "type": "category", + "label": "Deployment", + "link": { + "type": "doc", + "id": "deployment/deployment" }, - { - "type": "subcategory", - "label": "NMS", - "ids": [ - "nms/overview", - "nms/dashboard", - "nms/equipment", - "nms/network", - "nms/subscriber", - "nms/traffic", - "nms/metrics", - "nms/alerts", - "nms/federation", - "nms/admin", - "nms/tips_and_tricks" - ] - } - ], - "Architecture": [ - { - "type": "subcategory", - "label": "Access Gateway", - "ids": [ - "lte/architecture_overview" - ] + "items": [ + { + "type": "category", + "label": "Orchestrator (Orc8r)", + "items": [ + "orc8r/deploy_intro", + "orc8r/deploy_install", + "orc8r/deploy_using_ansible", + "orc8r/deploy_using_juju", + "orc8r/deploy_terraform_options", + "orc8r/deploy_faq" + ] + }, + { + "type": "category", + "label": "Network Management System (NMS)", + "items": [ + "nms/deploy_setup" + ] + }, + { + "type": "category", + "label": "Access Gateway (AGW)", + "items": [ + "lte/deploy_install", + "lte/deploy_install_docker", + "lte/deploy_agw_using_juju", + "lte/build_install_magma_pkg_in_agw", + "lte/deploy_config_enodebd", + "lte/deploy_config_apn" + ] + }, + { + "type": "category", + "label": "Federation Gateway (FEG)", + "items": [ + "feg/deploy_intro", + "feg/deploy_build", + "feg/deploy_install", + "feg/docker" + ] + }, + { + "type": "category", + "label": "Other Deployment Content", + "items": [ + "general/aws_cloudstrapper", + "dp/deploy_build", + "cwf/deploy_intro", + "cwf/deploy_build", + "cwf/deploy_install" + ] + } + ] + }, + { + "type": "category", + "label": "Configuration", + "link": { + "type": "doc", + "id": "configuration/configuration" }, - { - "type": "subcategory", - "label": "Orchestrator", - "ids": [ - "orc8r/architecture_overview", - "orc8r/architecture_modularity", - "orc8r/architecture_security" - ] - }, - { - "type": "subcategory", - "label": "NMS", - "ids": [ - "nms/architecture_overview" - ] - }, - { - "type": "subcategory", - "label": "FeG", - "ids": [ - "feg/architecture_overview" - ] - }, - { - "type": "subcategory", - "label": "Domain Proxy", - "ids": [ - "dp/architecture_overview" - ] - } - ], - "Deploy": [ - { - "type": "subcategory", - "label": "General", - "ids": [ - "general/aws_cloudstrapper" - ] - }, - { - "type": "subcategory", - "label": "Access Gateway", - "ids": [ - "lte/deploy_install", - "lte/deploy_install_docker", - "lte/deploy_config_agw", - "lte/deploy_config_enodebd", - "lte/deploy_config_apn", - "lte/deploy_agw_using_juju", - "lte/build_install_magma_pkg_in_agw" - ] - }, - { - "type": "subcategory", - "label": "Orchestrator", - "ids": [ - "orc8r/deploy_intro", - "orc8r/deploy_install", - "orc8r/deploy_using_ansible", - "orc8r/deploy_using_juju", - "orc8r/deploy_terraform_options", - "orc8r/deploy_faq" - ] - }, - { - "type": "subcategory", - "label": "NMS", - "ids": [ - "nms/deploy_setup" - ] - }, - { - "type": "subcategory", - "label": "Federation Gateway", - "ids": [ - "feg/deploy_intro", - "feg/deploy_build", - "feg/deploy_install" - ] - }, - { - "type": "subcategory", - "label": "Domain Proxy", - "ids": [ - "dp/deploy_build" - ] - }, - { - "type": "subcategory", - "label": "Carrier WiFi", - "ids": [ - "cwf/deploy_intro", - "cwf/deploy_build", - "cwf/deploy_install" - ] - } - ], - "Configure": [ - { - "type": "subcategory", - "label": "Access Gateway", - "ids": [ - "lte/configure_agw_ha", - "lte/configure_sentry" - ] - }, - { - "type": "subcategory", - "label": "Orchestrator", - "ids": [ - "orc8r/configure_thanos" - ] - }, - { - "type": "subcategory", - "label": "Federation Gateway", - "ids": [ - "feg/configure_federation" - ] - }, - { - "type": "subcategory", - "label": "NMS", - "ids": [ - "nms/nms_organizations" - ] - } - ], - "Upgrade": [ - { - "type": "subcategory", - "label": "General", - "ids": [ - "general/upgrade_intro" - ] - }, - { - "type": "subcategory", - "label": "Access Gateway", - "ids": [ - "lte/upgrade_debian_to_ubuntu", - "lte/upgrade_1_6", - "lte/upgrade_1_5", - "lte/upgrade_1_4", - "lte/upgrade_1_3", - "lte/upgrade_1_2", - "lte/upgrade_1_1" - ] - }, - { - "type": "subcategory", - "label": "Orchestrator", - "ids": [ - "orc8r/upgrade_intro", - "orc8r/upgrade_1_6", - "orc8r/upgrade_1_5", - "orc8r/upgrade_1_4", - "orc8r/upgrade_1_3", - "orc8r/upgrade_1_2", - "orc8r/upgrade_1_1" - ] - } - ], - "Debug": [ - { - "type": "subcategory", - "label": "General", - "ids": [ - "howtos/troubleshooting/agw_healthcheck", - "howtos/troubleshooting/agw_unable_to_checkin", - "howtos/troubleshooting/user_unable_to_attach", - "howtos/troubleshooting/update_certificates", - "howtos/troubleshooting/generate_admin_operator_certificates", - "howtos/troubleshooting/analyze_service_crashes_in_agw", - "howtos/troubleshooting/datapath_connectivity" - ] - }, - { - "type": "subcategory", - "label": "Access Gateway", - "ids": [ - "lte/debug_show_tech", - "lte/debug_dp_probe", - "lte/debug_user_control_plane" - ] - }, - { - "type": "subcategory", - "label": "Federated Gateway", - "ids": [ - "feg/debug_cli" - ] - }, - { - "type": "subcategory", - "label": "Carrier WiFi", - "ids": [ - "cwf/healthchecker", - "cwf/pipelined_packet_tracer_debugging" - ] - }, - { - "type": "subcategory", - "label": "Orchestrator", - "ids": [ - "orc8r/debug_logs" - ] - }, - { - "type": "subcategory", - "label": "NMS", - "ids": [ - "nms/alerts_troubleshooting" - ] - }, - { - "type": "subcategory", - "label": "Domain Proxy", - "ids": [ - "dp/debug_logs" - ] - } - ], - "Contribute": [ - "contributing/contribute_github", - "contributing/contribute_codeowners", - "contributing/contribute_tsc_norms", - "contributing/contribute_proposals" - ], - "Technical Reference": [ - { - "type": "subcategory", - "label": "General", - "ids": [ - "resources/ref_pcap", - "resources/ref_useful_links", - "resources/ref_magma_metrics" - ] - }, - { - "type": "subcategory", - "label": "Access Gateway", - "ids": [ - "lte/readme_agw", - "lte/dev_notes", - "lte/openvswitch", - "lte/pipelined", - "lte/ebpf_datapath", - "lte/ipfix", - "lte/pipelined_tests", - "lte/dev_unit_testing", - "lte/tr069", - "lte/s1ap_tests", - "lte/eventd", - "lte/sessiond", - "lte/access_service_restrictions", - "lte/dev_teid_allocation", - "lte/integrated_5g_sa", - "lte/extended_5g_sa_features", - "lte/suci_extensions", - "lte/redirectd", - "lte/readme_callflow", - "lte/readme_callflow", - "lte/GTPU_Extension_Header" - ] - }, - { - "type": "subcategory", - "label": "Orchestrator", - "ids": [ - "orc8r/dev_rest_api", - "orc8r/dev_build", - "orc8r/dev_testing", - "orc8r/dev_minikube", - "orc8r/dev_security", - "orc8r/dev_indexers", - "orc8r/dev_sub_digests", - "orc8r/dev_rest_api_auth", - "orc8r/dev_dependencies", - "orc8r/dev_gateway_registration", - "orc8r/dev_aws_stack" - ] - }, - { - "type": "subcategory", - "label": "NMS", - "ids": [ - "nms/dev_spacing", - "nms/dev_testing", - "nms/dev_themes", - "nms/dev_components" - ] - }, - { - "type": "subcategory", - "label": "Federation Gateway", - "ids": [ - "feg/dev_testing", - "feg/docker", - "feg/s1ap_federated_tests", - "feg/session_proxy" - ] - }, - { - "type": "subcategory", - "label": "Carrier WiFi", - "ids": [ - "cwf/dev_testing" - ] - } - ], - "Design Documents": [ - { - "type": "subcategory", - "label": "General", - "ids": [ - "proposals/p001_vpn_config_from_api", - "proposals/p005_call_tracing", - "proposals/p014_proposal_process", - "proposals/p015_tech_debt_week", - "proposals/p017_apn_refactoring" - ] - }, - { - "type": "subcategory", - "label": "Access Gateway", - "ids": [ - "proposals/p003_qos_enforcement", - "proposals/p004_fua_restrict_feature", - "proposals/p007_header_enrichment", - "proposals/p008_apn_correction", - "proposals/p013_Ubuntu_upgrade", - "proposals/p018_control_network_metrics", - "proposals/p019_enodeb_cbrs_support", - "proposals/p020_sgi_tunnel_transport" - ] - }, - { - "type": "subcategory", - "label": "Orchestrator", - "ids": [ - "proposals/p002_scaled_prometheus_pipeline", - "proposals/p010_subscriber_scaling", - "proposals/p011_victoriametrics" - ] - }, - { - "type": "subcategory", - "label": "NMS", - "ids": [ - "proposals/p009_nms_mariadb_migration", - "proposals/p016_nms_regression_testing" - ] - } - ], - "FAQ": [ - "faq/faq_magma" - ] - } + "items": [ + { + "type": "doc", + "id": "lte/deploy_config_agw", + "label": "First Time Setup" + }, + { + "type": "doc", + "id": "howtos/5g_nsa_support", + "label": "Enabling 5G" + }, + { + "type": "category", + "label": "Access Gateway", + "items": [ + "lte/configure_agw_ha", + "lte/configure_sentry", + "howtos/config_agw_bridged", + "howtos/he_api", + "howtos/ipv6_agw", + "howtos/inbound_roaming", + "howtos/l3_transport" + ] + }, + { + "type": "category", + "label": "Orchestrator", + "items": [ + "orc8r/configure_thanos" + ] + }, + { + "type": "category", + "label": "Federation Gateway", + "items": [ + "feg/configure_federation" + ] + }, + { + "type": "category", + "label": "NMS", + "items": [ + "nms/nms_organizations" + ] + } + ] + }, + { + "type": "category", + "label": "Getting Started", + "items": [ + "basics/prerequisites", + "basics/quick_start_guide", + "bazel/agw_with_bazel" + ] + }, + { + "type": "category", + "label": "Tutorials", + "items": [ + { + "type": "category", + "label": "Operate your own private mobile network with Charmed Magma", + "items": [ + "tutorials/00_overview", + "tutorials/01_getting_started", + "tutorials/02_deploying_magma_orchestrator", + "tutorials/03_deploying_magma_agw", + "tutorials/04_integrating_agw_with_orc8r", + "tutorials/05_deploying_the_radio_simulator", + "tutorials/06_simulating_user_traffic", + "tutorials/06_destroying_the_env" + ] + } + ] + }, + { + "type": "category", + "label": "Usage", + "items": [ + { + "type": "category", + "label": "How-To", + "items": [ + "howtos/ue_metering", + "howtos/call_tracing", + "howtos/events_monitoring", + "howtos/network_probe", + "howtos/package" + ] + }, + { + "type": "category", + "label": "NMS", + "items": [ + "nms/overview", + "nms/dashboard", + "nms/equipment", + "nms/network", + "nms/subscriber", + "nms/traffic", + "nms/metrics", + "nms/alerts", + "nms/federation", + "nms/admin", + "nms/tips_and_tricks" + ] + } + ] + }, + { + "type": "category", + "label": "Architecture", + "items": [ + { + "type": "category", + "label": "Access Gateway", + "items": [ + "lte/architecture_overview" + ] + }, + { + "type": "category", + "label": "Orchestrator", + "items": [ + "orc8r/architecture_overview", + "orc8r/architecture_modularity", + "orc8r/architecture_security" + ] + }, + { + "type": "category", + "label": "NMS", + "items": [ + "nms/architecture_overview" + ] + }, + { + "type": "category", + "label": "FeG", + "items": [ + "feg/architecture_overview" + ] + }, + { + "type": "category", + "label": "Domain Proxy", + "items": [ + "dp/architecture_overview" + ] + } + ] + }, + { + "type": "category", + "label": "Magma Use Cases", + "items": [ + { + "type": "doc", + "id": "feg/deploy_intro", + "label": "Federation Gateway Integration" + }, + { + "type": "doc", + "id": "cwf/deploy_intro", + "label": "CWAG Integration" + } + ] + }, + { + "type": "category", + "label": "Upgrade", + "items": [ + { + "type": "category", + "label": "General", + "items": [ + "general/upgrade_intro" + ] + }, + { + "type": "category", + "label": "Access Gateway", + "items": [ + "lte/upgrade_debian_to_ubuntu", + "lte/upgrade_1_6", + "lte/upgrade_1_5", + "lte/upgrade_1_4", + "lte/upgrade_1_3", + "lte/upgrade_1_2", + "lte/upgrade_1_1" + ] + }, + { + "type": "category", + "label": "Orchestrator", + "items": [ + "orc8r/upgrade_intro", + "orc8r/upgrade_1_6", + "orc8r/upgrade_1_5", + "orc8r/upgrade_1_4", + "orc8r/upgrade_1_3", + "orc8r/upgrade_1_2", + "orc8r/upgrade_1_1" + ] + } + ] + }, + { + "type": "category", + "label": "Debug", + "items": [ + { + "type": "category", + "label": "General", + "items": [ + "howtos/troubleshooting/agw_healthcheck", + "howtos/troubleshooting/agw_unable_to_checkin", + "howtos/troubleshooting/user_unable_to_attach", + "howtos/troubleshooting/update_certificates", + "howtos/troubleshooting/generate_admin_operator_certificates", + "howtos/troubleshooting/analyze_service_crashes_in_agw", + "howtos/troubleshooting/datapath_connectivity" + ] + }, + { + "type": "category", + "label": "Access Gateway", + "items": [ + "lte/debug_show_tech", + "lte/debug_dp_probe", + "lte/debug_user_control_plane" + ] + }, + { + "type": "category", + "label": "Federated Gateway", + "items": [ + "feg/debug_cli" + ] + }, + { + "type": "category", + "label": "Carrier WiFi", + "items": [ + "cwf/healthchecker", + "cwf/pipelined_packet_tracer_debugging" + ] + }, + { + "type": "category", + "label": "Orchestrator", + "items": [ + "orc8r/debug_logs" + ] + }, + { + "type": "category", + "label": "NMS", + "items": [ + "nms/alerts_troubleshooting" + ] + }, + { + "type": "category", + "label": "Domain Proxy", + "items": [ + "dp/debug_logs" + ] + } + ] + }, + { + "type": "category", + "label": "Contribute", + "items": [ + "contributing/contribute_github", + "contributing/contribute_codeowners", + "contributing/contribute_tsc_norms", + "contributing/contribute_proposals", + "contributing/development_workflows" + ] + }, + { + "type": "category", + "label": "Technical Reference", + "items": [ + { + "type": "category", + "label": "General", + "items": [ + "resources/ref_pcap", + "resources/ref_useful_links", + "resources/ref_magma_metrics" + ] + }, + { + "type": "category", + "label": "Access Gateway", + "items": [ + "lte/readme_agw", + "lte/dev_notes", + "lte/openvswitch", + "lte/pipelined", + "lte/ebpf_datapath", + "lte/ipfix", + "lte/pipelined_tests", + "lte/dev_unit_testing", + "lte/tr069", + "lte/s1ap_tests", + "lte/eventd", + "lte/sessiond", + "lte/access_service_restrictions", + "lte/dev_teid_allocation", + "lte/integrated_5g_sa", + "lte/extended_5g_sa_features", + "lte/suci_extensions", + "lte/redirectd", + "lte/readme_callflow", + "lte/GTPU_Extension_Header" + ] + }, + { + "type": "category", + "label": "Orchestrator", + "items": [ + "orc8r/dev_rest_api", + "orc8r/dev_build", + "orc8r/dev_testing", + "orc8r/dev_minikube", + "orc8r/dev_security", + "orc8r/dev_indexers", + "orc8r/dev_sub_digests", + "orc8r/dev_rest_api_auth", + "orc8r/dev_dependencies", + "orc8r/dev_gateway_registration", + "orc8r/dev_aws_stack" + ] + }, + { + "type": "category", + "label": "NMS", + "items": [ + "nms/dev_spacing", + "nms/dev_testing", + "nms/dev_themes", + "nms/dev_components" + ] + }, + { + "type": "category", + "label": "Federation Gateway", + "items": [ + "feg/dev_testing", + "feg/docker", + "feg/s1ap_federated_tests", + "feg/session_proxy" + ] + }, + { + "type": "category", + "label": "Carrier WiFi", + "items": [ + "cwf/dev_testing" + ] + } + ] + }, + { + "type": "category", + "label": "Design Documents", + "items": [ + { + "type": "category", + "label": "General", + "items": [ + "proposals/p001_vpn_config_from_api", + "proposals/p005_call_tracing", + "proposals/p014_proposal_process", + "proposals/p015_tech_debt_week", + "proposals/p017_apn_refactoring" + ] + }, + { + "type": "category", + "label": "Access Gateway", + "items": [ + "proposals/p003_qos_enforcement", + "proposals/p004_fua_restrict_feature", + "proposals/p007_header_enrichment", + "proposals/p008_apn_correction", + "proposals/p013_Ubuntu_upgrade", + "proposals/p018_control_network_metrics", + "proposals/p019_enodeb_cbrs_support", + "proposals/p020_sgi_tunnel_transport" + ] + }, + { + "type": "category", + "label": "Orchestrator", + "items": [ + "proposals/p002_scaled_prometheus_pipeline", + "proposals/p010_subscriber_scaling", + "proposals/p011_victoriametrics" + ] + }, + { + "type": "category", + "label": "NMS", + "items": [ + "proposals/p009_nms_mariadb_migration", + "proposals/p016_nms_regression_testing" + ] + } + ] + }, + { + "type": "category", + "label": "FAQ", + "items": [ + "faq/faq_magma" + ] + } + ] } diff --git a/readmes/configuration/configuration.md b/readmes/configuration/configuration.md new file mode 100644 index 0000000..5ec8280 --- /dev/null +++ b/readmes/configuration/configuration.md @@ -0,0 +1,85 @@ +# Configuration Overview + +This document provides an overview of the configuration process for various components of the Magma platform. Proper configuration is crucial for ensuring optimal performance, security, and compatibility across your deployment. + +## Introduction + +Configuration in Magma involves setting up parameters for different components such as the Access Gateway (AGW), Orchestrator (Orc8r), Network Management System (NMS), and Federation Gateway (FEG). Each component has specific configuration needs that must be addressed to ensure seamless operation. Configuration tasks typically include defining network settings, integrating with external systems, managing user access, and optimizing performance through specific parameter tuning. + +Configuration in Magma can be performed through various methods including configuration files, the Magma NMS (Network Management System) UI, and API calls. Understanding the specific requirements of your deployment environment—whether it's a small-scale test setup or a large-scale production network—will guide the configuration process. + +## Key Configuration Areas + +- **Access Gateway (AGW):** Configuring network settings, high availability, and specific features like 5G support. +- **Orchestrator (Orc8r):** Setting up Thanos for metrics and other cloud service configurations. +- **Network Management System (NMS):** Managing organizational settings and user permissions. +- **Federation Gateway (FEG):** Configuring federation parameters for integration with other networks. + +## Configuration Methods and Tools + +### 1. Configuration Files + +Many Magma components rely on YAML or JSON configuration files to define operational parameters. These files are typically located in directories such as `/etc/magma/` or `/var/opt/magma/configs/` on the respective hosts (AGW or Orc8r VMs). Key configuration files include: + +- **`control_proxy.yml`**: Manages communication settings between the gateway and the Orchestrator. + +### 2. Network Management System (NMS) UI + +The NMS provides a user-friendly interface for configuring network-wide settings, gateway parameters, and subscriber policies. Key configuration tasks in the NMS include: + +- **Network Configuration**: Setting up EPC (Evolved Packet Core) and RAN (Radio Access Network) parameters such as bandwidth, frequency bands (TDD/FDD), and authentication settings under the 'Network' tab. +- **Gateway Configuration**: Registering and configuring AGWs, including setting up high availability and specific LTE parameters. +- **Subscriber Management**: Defining subscriber profiles and policies for traffic management. + +Access the NMS via a web browser using the Orchestrator's URL (typically `https:///nms`) and log in with administrative credentials to make configuration changes. + +### 3. API and Swagger Interface + +For advanced users and automation, Magma offers RESTful APIs to configure components programmatically. The Swagger UI, accessible through the Orchestrator, provides a detailed interface to explore and execute API calls for tasks like: + +- Configuring roaming settings for federation networks. +- Updating gateway configurations. +- Managing alert rules and receivers. + +### 4. Command-Line Tools + +Certain configurations, especially on the AGW, can be managed via command-line scripts provided by Magma. For instance, `config_cli.py` can be used to set log levels or other runtime parameters without editing files directly. + +## Best Practices for Configuration + +- **Backup Configurations**: Always back up existing configuration files before making changes to prevent loss of working settings. Store backups in a secure location. +- **Document Changes**: Maintain a log of configuration changes, especially for production environments, to track what was changed and why. +- **Test in Staging**: For critical deployments, test configuration changes in a staging environment before applying them to production to minimize risks of downtime. +- **Use Version Control**: If possible, manage configuration files in a version control system to track changes over time and roll back if necessary. +- **Validate Settings**: After applying configurations, validate them by checking logs (e.g., using `journalctl -fu magma@magmad` on AGW) to ensure services are running as expected without errors. + +## Common Configuration Challenges + +- **Connectivity Issues**: Misconfigured network settings or IP addresses in `control_proxy.yml` can prevent AGWs from checking into the Orchestrator. Ensure correct IP addresses and ports are specified. +- **Service Restarts**: Forgetting to restart services after configuration changes can lead to settings not taking effect. Always restart relevant services like `magmad` or specific component services. +- **API Authentication Errors**: When using the API, ensure correct authentication tokens or credentials are used to avoid access denied errors. +- **Parameter Conflicts**: Inconsistent settings across components (e.g., mismatched PLMN IDs between AGW and Orc8r) can cause operational issues. Cross-check settings for consistency. + +## Component-Specific Configuration Highlights + +### Access Gateway (AGW) + +- **High Availability (HA)**: Configure AGW for HA by setting up primary and secondary gateways with appropriate network interface configurations in AWS or other environments. Modify `mme.yml` to enable HA features. +- **5G NSA Support**: Enable 5G Non-Standalone (NSA) support by ensuring relevant parameters are set in the LTE network configuration through NMS or API. + +### Orchestrator (Orc8r) + +- **Metrics with Thanos**: Configure Thanos for long-term metrics storage by updating relevant configuration files or using the NMS to set retention policies and storage options. +- **Service Registry**: Ensure service registry configurations in `service_registry.yml` are accurate to manage inter-service communications. + +### Network Management System (NMS) + +- **User Roles**: Configure user permissions (superuser, user, readonly) under the 'Admin' section to control access to configuration capabilities. +- **Organizations**: Set up organizational structures to manage multiple networks or tenants effectively within the NMS. + +### Federation Gateway (FEG) + +- **Roaming Configurations**: Use the Swagger API to configure S6a and S8 interfaces for roaming partnerships, ensuring correct routing based on PLMN IDs. +- **Integration Settings**: Define parameters for integration with external HSS and PGW systems to handle federated subscribers. + +Navigate through the subcategories in the sidebar for detailed configuration guides for each component. These guides provide step-by-step instructions tailored to specific use cases and deployment scenarios. diff --git a/readmes/contributing/development_workflows.md b/readmes/contributing/development_workflows.md new file mode 100644 index 0000000..28c8b96 --- /dev/null +++ b/readmes/contributing/development_workflows.md @@ -0,0 +1,105 @@ +# Development Workflows for Magma + +## Introduction +This document outlines the recommended development workflows for contributing to Magma. Whether you're a new contributor or an experienced developer, following these workflows will help streamline your development process and ensure compatibility with the Magma codebase. This guide covers setting up development environments using devcontainers, managing container updates, and provides directions for tackling "good first issue" tasks. + +## Development Environment Setup with Devcontainers +Devcontainers (Development Containers) provide a consistent, reproducible development environment using Docker, ensuring that all developers work with the same tools and dependencies. This approach minimizes "works on my machine" issues and simplifies onboarding for new contributors. + +### Prerequisites +- **Docker**: Ensure Docker is installed on your system. Follow the [Docker installation guide](https://docs.docker.com/get-docker/) for your operating system. +- **Visual Studio Code**: Recommended for devcontainer support. Install VS Code and the "Remote - Containers" extension. +- **Devcontainer extention**: + +### Setting Up a Devcontainer for Magma +1. **Clone the Magma Repository**: + ```bash + git clone https://github.com/magma/magma.git + cd magma + ``` +2. **Open in VS Code**: + - Open the cloned repository in Visual Studio Code. + - Use the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P` on macOS) and select "Remote-Containers: Reopen in Container". +3. **Configuration**: + - The `.devcontainer` extention builds the necessary docker image with all developments tools needed, this image contains the configuration for the development environment. + - The container will build with all necessary dependencies for Magma development, including build tools, libraries, and runtime environments. +4. **Start Developing**: + - Once the container is running, your VS Code environment will be inside the container, with access to all required tools. + - Use terminal commands within VS Code to build, test, and run Magma components. + +### Benefits of Devcontainers +- **Consistency**: All developers use the same environment, reducing discrepancies. +- **Isolation**: Development environment is isolated from your local system, preventing conflicts with other projects. +- **Ease of Setup**: New contributors can get started quickly without manual dependency installation. + +For more details on devcontainers, refer to the [VS Code Remote - Containers documentation](https://code.visualstudio.com/docs/remote/containers). + +## Managing Container Updates +When working with containerized environments or deploying Magma components via Docker, keeping containers updated is crucial for security, performance, and compatibility with the latest Magma features. + +### Updating Development Containers +- **Rebuild the Container**: If the `.devcontainer` configuration or Dockerfile changes, rebuild the container using "Remote-Containers: Rebuild Container" from the VS Code Command Palette. +- **Pull Latest Images**: Ensure the base Docker images used in the devcontainer are up-to-date by running: + ```bash + docker pull + ``` + Check the `.devcontainer/Dockerfile` for the specific image names. + +### Updating Magma Deployment Containers + +- **Check for Updates**: Regularly check the Magma GitHub repository or Docker Hub for updates to official Magma images. +- **Pull Updated Images**: For components deployed via Docker (e.g., AGW, FEG), update images with: + ```bash + docker pull magmacore/: + ``` + Replace `` with the specific Magma component (e.g., `agw`, `orc8r`) and `` with the desired version or `latest`. +- **Redeploy Containers**: After pulling updates, redeploy the containers using your deployment scripts or Docker Compose files to apply the changes. +- **Version Compatibility**: Ensure that updated containers are compatible with your current Orchestrator (Orc8r) version. Refer to release notes on [GitHub](https://github.com/magma/magma/releases) for compatibility information. + +## Contributing to Magma: Good First Issues +Magma welcomes contributions from developers of all skill levels. If you're new to the project, starting with a "good first issue" is an excellent way to get involved, learn the codebase, and make a meaningful impact. + +### Why Contribute to Good First Issues? +- **Learning Opportunity**: These issues are typically well-documented and scoped for beginners, helping you understand Magma's architecture and coding standards. +- **Community Impact**: Even small contributions improve the project for all users, from bug fixes to documentation updates. +- **Mentorship**: The Magma community often provides guidance on these issues through GitHub comments or Slack discussions. + +### Finding Good First Issues +- Visit the [Magma GitHub Issues page](https://github.com/magma/magma/issues) and filter for issues labeled "good first issue". +- These issues might include tasks like fixing typos in documentation, writing unit tests, or implementing small features. + +### How to Get Started +1. **Claim an Issue**: Comment on the issue to express interest, ensuring no one else is already working on it. +2. **Set Up Your Environment**: Use the devcontainer setup described above or follow the [development setup guide](https://github.com/magma/magma/blob/master/docs/basics/quick_start_guide.md) for a local environment. +3. **Submit a Pull Request (PR)**: Follow the [contribution guidelines](https://github.com/magma/magma/blob/master/CONTRIBUTING.md) to submit your changes for review. +4. **Engage with Reviewers**: Address feedback from maintainers to refine your contribution. + +### Incentives for Contribution +- **Recognition**: Contributors are acknowledged in release notes and community channels. +- **Skill Development**: Gain experience in mobile networking, open-source collaboration, and cutting-edge technologies like 5G. +- **Networking**: Connect with other developers, operators, and organizations in the Magma community. + +## Community Engagement: Attend Meetings +Beyond code contributions, participating in community meetings is a valuable way to engage with Magma's development roadmap, discuss issues, and collaborate on solutions. + +### Magma Community Meetings +- **Technical Steering Committee (TSC) Meetings**: Held regularly to discuss project direction, feature prioritization, and governance. Check the [Magma Slack](https://magma-developers.slack.com/) or [GitHub Discussions](https://github.com/magma/magma/discussions) for schedules and agendas. +- **Working Groups**: Focused sessions on specific components (e.g., AGW, Orc8r) or topics (e.g., 5G integration). These are great for deep dives into areas of interest. + +### How to Join +- **Slack**: Join the Magma Slack workspace for real-time updates and meeting invites. +- **Calendar**: Meeting links and times are often shared in the community calendar or GitHub repository. +- **Prepare**: Review agendas and bring questions or topics to discuss, especially if you're working on a specific issue or feature. + +### Benefits of Attending +- **Influence Development**: Provide input on upcoming features and priorities. +- **Learn from Peers**: Gain insights from experienced contributors and deployers. +- **Build Connections**: Establish relationships that can lead to mentorship or collaboration opportunities. + +## Next Steps +- Set up your development environment using devcontainers to start coding on Magma. +- Explore "good first issue" tasks on GitHub to make your first contribution. +- Join a community meeting to connect with other Magma contributors and learn about ongoing efforts. +- For detailed contribution guidelines, refer to [Contributing to Magma](../contributing/contribute_github.md). + +We encourage all developers to dive in, ask questions on [Slack](https://magma-developers.slack.com/), and help shape the future of Magma! diff --git a/readmes/deployment/deployment.md b/readmes/deployment/deployment.md new file mode 100644 index 0000000..4408354 --- /dev/null +++ b/readmes/deployment/deployment.md @@ -0,0 +1,76 @@ +# Deployment + +## Introduction +This document provides an overview of deploying Magma. It covers the three main deployment modes - Kubernetes, Docker, and Baremetal. This page serves as a starting point for deployers aiming to set up Magma for operational use. + +## Main Deployment Modes +Magma can be deployed using three primary modes, each suited to different scales and technical proficiencies. Below is an overview of these modes to help you choose the right approach for your needs. + +### 1. Docker +**Overview**: Docker provides a lightweight, containerized approach for simpler deployments, often used for testing or small to medium-scale setups. It is accessible for deploying components like AGW or Federation Gateway (FEG). +- **Use Case**: Ideal for pilot projects, lab environments, or deployments with 50-200 users. +- **Expertise Required**: Beginner to intermediate; basic understanding of containerization is helpful. +- **Benefits**: Easy to set up, portable, and resource-efficient. +- **Challenges**: Limited scalability compared to Kubernetes; may require manual scaling. +- **Relevant Guides**: Refer to component-specific Docker deployment guides below. + +### 2. Kubernetes +**Overview**: Kubernetes is ideal for medium to large-scale deployments requiring high availability and scalability. It is commonly used for the Orchestrator (Orc8r) to manage multiple Access Gateways (AGWs) across distributed environments. +- **Use Case**: Suitable for campus networks or regional operators managing hundreds to thousands of users. +- **Expertise Required**: Advanced; requires familiarity with cluster management and orchestration tools. +- **Benefits**: Offers robust scaling, automated recovery, and centralized management. +- **Challenges**: Complex setup and maintenance; higher resource demands. +- **Relevant Guides**: See specific component deployment guides under each component section for Kubernetes options. + +### 3. Baremetal +**Overview**: Baremetal deployment involves installing Magma components directly on physical or virtual servers, offering maximum performance for small-scale or high-performance needs. It is often used for AGW in constrained environments. +- **Use Case**: Best for small enterprises, rural setups, or edge locations with minimal infrastructure. +- **Expertise Required**: Intermediate; requires knowledge of system administration and manual configuration. +- **Benefits**: High performance, cost-effective for small setups, full control over hardware. +- **Challenges**: Lacks automated scaling and recovery; manual updates and maintenance. +- **Relevant Guides**: Check component-specific Baremetal installation guides in the sections below. + +## Magma Components Overview +Magma consists of several key components, each with specific roles in the network architecture. Below is a summary of each component, with links to detailed technical references and deployment guides for each deployment mode where applicable. + +### Orchestrator (Orc8r) +**Overview**: The Orchestrator is the central management system for Magma, handling configuration, monitoring, and policy enforcement across the network. It is critical for managing multiple AGWs and integrating with external systems. +- **Technical Reference**: [Orchestrator Architecture](../orc8r/architecture_overview.md) +- **Deployment Guides**: + - **Kubernetes**: [Deploying Orc8r with Juju](../orc8r/deploy_using_juju.md) + - **Baremetal**: [Baremetal Installation](../orc8r/deploy_install.md) + - **Additional Guides**: [Ansible Deployment](../orc8r/deploy_using_ansible.md), [Terraform Options](../orc8r/deploy_terraform_options.md), [FAQ](../orc8r/deploy_faq.md) + +### Network Management System (NMS) +**Overview**: The NMS provides a user-friendly interface for network operators to monitor, configure, and manage Magma networks, offering dashboards for traffic, subscribers, and alerts. +- **Technical Reference**: [NMS Architecture](../nms/architecture_overview.md) +- **Deployment Guides**: + - **General**: [NMS Setup](../nms/deploy_setup.md) + +### Access Gateway (AGW) +**Overview**: The Access Gateway manages radio access and core network functions, serving as the primary interface for user equipment (UE) in LTE and 5G networks. It handles traffic routing and policy enforcement at the edge. +- **Technical Reference**: [Access Gateway Architecture](../lte/readme_agw.md) +- **Deployment Guides**: + - **Docker**: [AGW Docker Installation](../lte/deploy_install_docker.md) + - **Baremetal**: [AGW Baremetal Installation](../lte/deploy_install.md) + - **Kubernetes**: [Deploy AGW with Juju](../lte/deploy_agw_using_juju.md) + - **Additional Guides**: [Build and Install Magma Package on AGW](../lte/build_install_magma_pkg_in_agw.md) + +### Federation Gateway (FEG) +**Overview**: The Federation Gateway enables roaming and interconnection with external networks, facilitating partnerships with other operators for seamless user connectivity across different network domains. +- **Technical Reference**: [Federation Gateway Architecture](../feg/architecture_overview.md) +- **Deployment Guides**: + - **Docker**: [FEG Docker Deployment](../feg/docker.md) + - **Baremetal**: [FEG Installation](../feg/deploy_install.md) + - **Additional Guides**: [FEG Introduction](../feg/deploy_intro.md), [Build FEG](../feg/deploy_build.md) + +## Choosing the Right Deployment Mode +- **Scale**: For small-scale (under 50 users), Baremetal or Docker is sufficient; for medium to large-scale (hundreds to thousands of users), Kubernetes offers better scalability. +- **Use Case**: Edge or rural deployments may favor Baremetal for performance; federated networks with roaming needs require FEG; centralized management benefits from Kubernetes for Orc8r. +- **Expertise**: Beginners may start with Docker for ease; advanced users can leverage Kubernetes for robustness; Baremetal suits those comfortable with system-level configuration. + +## Community Contributions +Deployment strategies evolve with community input. We encourage deployers to share their setups, challenges, and solutions on [GitHub](https://github.com/magma/magma) or [Slack](https://magma-developers.slack.com/) to enhance this knowledge base. For contributing guidelines, see [Contributing to Magma](../contributing/contribute_github.md). + +## Next Steps +After identifying the appropriate deployment mode and components for your needs, refer to the specific guides linked above for detailed instructions. For troubleshooting deployment issues, consult the [Debugging Section](../howtos/troubleshooting/agw_healthcheck.md) for common problems and solutions.