From 44be5f3667d575ac4742feb69efacbf52fa6bd5d Mon Sep 17 00:00:00 2001 From: spirizeon Date: Sun, 3 May 2026 22:56:23 +0530 Subject: [PATCH 1/7] docs: remove Vagrant documentation and add deprecation notice - Removed Vagrant and VirtualBox from prerequisites (macOS and Ubuntu) - Replaced Vagrant-based AGW setup with Docker-based deployment - Added deprecation notice in introduction.md directing users to Docker - Updated quick_start_guide.md to use agw_docker_install.sh - Part of Issue #45: Remove Vagrant Documentation from Magma Documentation Repository See: magma/magma#15754 --- docusaurus/docs/basics/prerequisites.md | 5 +- docusaurus/docs/basics/quick_start_guide.md | 89 +++++--------- readmes/basics/introduction.md | 9 ++ readmes/basics/prerequisites.md | 13 --- readmes/basics/quick_start_guide.md | 121 +++++--------------- 5 files changed, 63 insertions(+), 174 deletions(-) diff --git a/docusaurus/docs/basics/prerequisites.md b/docusaurus/docs/basics/prerequisites.md index a437f5e..85da8e1 100644 --- a/docusaurus/docs/basics/prerequisites.md +++ b/docusaurus/docs/basics/prerequisites.md @@ -15,17 +15,16 @@ Install the following tools: 1. [Docker](https://www.docker.com) and Docker Compose 2. [Homebrew](https://brew.sh/) *only* for MacOS users -3. [VirtualBox](https://www.virtualbox.org/) -3. [Vagrant](https://vagrantup.com) Replace `brew` with your OS-appropriate package manager as necessary: ```bash brew install python3 pip3 install ansible fabric3 jsonpickle requests PyYAML -vagrant plugin install vagrant-vbguest ``` +> **Note**: Vagrant-based development has been deprecated. Please use the Docker-based AGW deployment instead. + If you are on MacOS, you should start Docker for Mac and increase the memory allocation for the Docker engine to at least 4GB (Preferences -> Advanced). diff --git a/docusaurus/docs/basics/quick_start_guide.md b/docusaurus/docs/basics/quick_start_guide.md index 1a9fdc2..2424bb3 100644 --- a/docusaurus/docs/basics/quick_start_guide.md +++ b/docusaurus/docs/basics/quick_start_guide.md @@ -12,36 +12,32 @@ installing Magma for a production deployment. With the [prereqs](prerequisites.md) installed, we can now set up a minimal end-to-end system on your development environment. In this guide, we'll start -by running the LTE access gateway and orchestrator cloud, and then +by running the LTE access gateway (via Docker) and orchestrator cloud, and then register your local access gateway with your local cloud for management. -We will be spinning up a virtual machine and some docker containers for this -full setup, so you'll probably want to do this on a system with at least 8GB -of memory. Our development VM's are in the 192.168.80.0/24 address space, so -make sure that you don't have anything running which hijacks that (e.g. VPN). +> **Note**: Vagrant-based development has been deprecated. Please use the +> Docker-based AGW deployment. See the [AGW Docker deployment guide](../deployment/agw/docker.md) +> for the latest instructions. -In the following steps, note the prefix in terminal commands. `HOST` means to -run the indicated command on your host machine, and `MAGMA-VM` on the `magma` -vagrant machine under `lte/gateway`. +We will be spinning up docker containers for this full setup, so you'll +probably want to do this on a system with at least 8GB of memory. ## Provisioning the environment -Go ahead and open up 2 fresh terminal tabs. Start in +Go ahead and open up 2 fresh terminal tabs. -### Terminal Tab 1: Provision the AGW VM +### Terminal Tab 1: Provision the AGW (Docker) -The development environment virtualizes the access gateway so you don't need -any production hardware on hand to test an end-to-end setup. -We'll be setting up the LTE AGW VM in this tab. +The development environment can use Docker to run the Access Gateway. See the +[AGW Docker deployment](../deployment/agw/docker.md) for detailed instructions. + +For quick setup: ```bash -HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ vagrant up magma +HOST [magma]$ cd lte/gateway/deploy +HOST [magma/lte/gateway/deploy]$ ./agw_docker_install.sh ``` -This will take a few minutes to spin up the VM. While that runs, switch over -to... - ### Terminal Tab 2: Build Orchestrator Here, we'll be building the Orchestrator docker containers. @@ -51,38 +47,12 @@ HOST [magma]$ cd orc8r/cloud/docker HOST [magma/orc8r/cloud/docker]$ ./build.py -a ``` -This will build all the docker images for Orchestrator. The `vagrant up` from -the first tab should finish before the image building, so you should switch -to that tab and move on for now. - ## Initial Run -Once `vagrant up` in the first tab finishes: - -### Terminal Tab 1: Build AGW from Source - -We will kick off the initial build of the AGW from source here. - -```bash -HOST [magma/lte/gateway]$ vagrant ssh magma -MAGMA-VM [/home/vagrant]$ cd magma/lte/gateway -MAGMA-VM [/home/vagrant/magma/lte/gateway]$ make run -``` - -This will take a while (we have a lot of CXX files to build). With 2 extensive -build jobs running, now is a good time to grab a coffee or lunch. The first -build ever from source will take a while, but afterwards, a persistent ccache -and Docker's native layer caching will speed up subsequent builds -significantly. - -You can monitor what happens in the other tab now: - ### Terminal Tab 2: Start Orchestrator Once the Orchestrator build finishes, we can start the development Orchestrator -cloud for the first time. We'll also use this time to register the local -client certificate you'll need to access the local API gateway for your -development stack. +cloud for the first time. Starting Orchestrator is as simple as: @@ -123,31 +93,23 @@ installed client certificates. See [here](https://support.globalsign.com/custome for instructions. If you use Chrome or Safari, you may have to restart the browser before the certificate can be used. -### Connecting Your Local LTE Gateway to Your Local Cloud +### Register Your AGW with Orchestrator -At this point, you will have built all the code in the LTE access gateway and -the Orchestrator cloud. All the services on the LTE access gateway and -orchestrator cloud are running, but your gateway VM isn't yet set up to -communicate with your local cloud. - -We have a fabric command set up to do this: +Register your Docker-based AGW with Orchestrator: ```bash HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ fab -f dev_tools.py register_vm +HOST [magma/lte/gateway]$ fab -f dev_tools.py register_agw ``` -This command will seed your gateway and network on Orchestrator with some -default LTE configuration values and set your gateway VM up to talk to your -local Orchestrator cloud. Wait a minute or 2 for the changes to propagate, -then you can verify that things are working: +Wait a minute or 2 for the changes to propagate, then you can verify that things are working: ```bash -HOST [magma/lte/gateway]$ vagrant ssh magma +HOST [magma/lte/gateway]$ docker exec -it magma_control /bin/bash -MAGMA-VM$ sudo service magma@* stop -MAGMA-VM$ sudo service magma@magmad restart -MAGMA-VM$ sudo tail -f /var/log/syslog +MAGMA-CONTROL$ sudo service magma@* stop +MAGMA-CONTROL$ sudo service magma@magmad restart +MAGMA-CONTROL$ sudo tail -f /var/log/syslog # After a minute or 2 you should see these messages: Sep 27 22:57:35 magma-dev magmad[6226]: [2018-09-27 22:57:35,550 INFO root] Checkin Successful! @@ -172,6 +134,7 @@ After this, you will be able to access the UI by visiting and password `password1234`. If you see Gateway Error 502, don't worry, the NMS can take upto 60 seconds to finish starting up. +## Additional Resources - - +- For detailed AGW Docker deployment, see [AGW Docker deployment guide](../deployment/agw/docker.md) +- For testing LTE features without cloud-based network management, see [S1AP integration tests](../lte/s1ap_tests.md) \ No newline at end of file diff --git a/readmes/basics/introduction.md b/readmes/basics/introduction.md index 055a8f0..d1e408d 100644 --- a/readmes/basics/introduction.md +++ b/readmes/basics/introduction.md @@ -64,6 +64,15 @@ Magma leverages a variety of modern technologies to implement its solutions: - The main programming languages used in development. - Multiple language equals multiple opportunities to contribute. +## Deployment Methods + +Magma supports multiple deployment methods for the Access Gateway (AGW): + +- **Docker-based AGW** (Recommended): The modern, containerized approach for development and production. See the [AGW Docker deployment guide](./deployment/agw/docker.md). +- **Bare Metal**: For production deployments on physical hardware. + +> **Deprecation Notice**: Vagrant-based AGW deployment has been **deprecated** and will be removed in a future release. Please migrate to the Docker-based deployment method. + ## Community Join the [Magma Slack channel](https://join.slack.com/t/magmacore/shared_invite/zt-g76zkofr-g6~jYiS3KRzC9qhAISUC2A) and interact with our active community. diff --git a/readmes/basics/prerequisites.md b/readmes/basics/prerequisites.md index 872ce1d..4a549fd 100644 --- a/readmes/basics/prerequisites.md +++ b/readmes/basics/prerequisites.md @@ -27,8 +27,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e 1. [Docker and Docker Compose](https://docs.docker.com/desktop/install/mac-install/) 2. [Homebrew](https://brew.sh/) - 3. [VirtualBox](https://www.virtualbox.org/) - 4. [Vagrant](https://vagrantup.com) ```bash brew install go@1.20 pyenv @@ -42,7 +40,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e pyenv install 3.8.10 pyenv global 3.8.10 pip3 install ansible fabric jsonpickle requests PyYAML - vagrant plugin install vagrant-vbguest vagrant-disksize vagrant-reload ``` **Note**: In the case where installation of `fabric` through pip was unsuccessful, @@ -59,8 +56,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e 1. Install the following tools 1. [Docker and Docker Compose](https://docs.docker.com/engine/install/ubuntu/) - 2. [VirtualBox](https://www.virtualbox.org/wiki/Linux_Downloads) - 3. [Vagrant](https://www.vagrantup.com/downloads) 2. Install golang version 1.20.1. 1. Download the tar file. @@ -147,14 +142,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e pip3 install ansible fabric jsonpickle requests PyYAML ``` -5. Install `vagrant` necessary plugin. - - ```bash - vagrant plugin install vagrant-vbguest vagrant-disksize vagrant-reload - ``` - - Make sure `virtualbox` is the default provider for `vagrant` by adding the following line to your `.bashrc` (or equivalent) and restart your shell: `export VAGRANT_DEFAULT_PROVIDER="virtualbox"`. - ## Downloading Magma You can find Magma code on [Github](https://github.com/magma/magma). diff --git a/readmes/basics/quick_start_guide.md b/readmes/basics/quick_start_guide.md index 05cef95..cc903ba 100644 --- a/readmes/basics/quick_start_guide.md +++ b/readmes/basics/quick_start_guide.md @@ -11,47 +11,29 @@ installing Magma for a production deployment. With the [prereqs](prerequisites.md) installed, we can now set up a minimal end-to-end system on your development environment. In this guide, we'll start -by running the LTE access gateway and orchestrator cloud, and then +by running the LTE access gateway (via Docker) and orchestrator cloud, and then register your local access gateway with your local cloud for management. -We will be spinning up a virtual machine and some docker containers for this -full setup, so you'll probably want to do this on a system with at least 8GB -of memory. Our development VM's are in the 192.168.60.0/24, 192.168.128.0/24 and -192.168.129.0/24 address spaces, so make sure that you don't have anything -running which hijacks those (e.g. VPN). - -In the following steps, note the prefix in terminal commands. `HOST` means to -run the indicated command on your host machine, and `MAGMA-VM` on the `magma` -vagrant machine under `lte/gateway`. +> **Note**: Vagrant-based development has been deprecated. Please use the +> Docker-based AGW deployment. See the [AGW Docker deployment guide](../deployment/agw/docker.md) +> for the latest instructions. ## Provisioning the environment -Go ahead and open up 2 fresh terminal tabs. Start in +Go ahead and open up 2 fresh terminal tabs. -### Terminal Tab 1: Provision the AGW VM +### Terminal Tab 1: Provision the AGW (Docker) -The development environment virtualizes the access gateway, so you don't need -any production hardware on hand to test an end-to-end setup. -We'll be setting up the LTE AGW VM in this tab. +The development environment can use Docker to run the Access Gateway. See the +[AGW Docker deployment](../deployment/agw/docker.md) for detailed instructions. -You need to make sure that your local network setup is correct for the VM to -start properly. Especially the entries `* 192.168.0.0/16` and `* 3001::/64` must exist in your -`/etc/vbox/networks.conf`. +For quick setup: ```bash -HOST [magma]$ echo "* 192.168.0.0/16" | sudo tee -a /etc/vbox/networks.conf -HOST [magma]$ echo "* 3001::/64" | sudo tee -a /etc/vbox/networks.conf -HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ vagrant up magma +HOST [magma]$ cd lte/gateway/deploy +HOST [magma/lte/gateway/deploy]$ ./agw_docker_install.sh ``` -This will take a few minutes to spin up the VM. While that runs, switch over -to... - -**Note**: If you are looking to test/develop the LTE features of AGW, without -cloud based network management, you can skip the rest of this guide and try the -[S1AP integration tests](../lte/s1ap_tests.md) now. - ### Terminal Tab 2: Build Orchestrator Here, we'll be building the Orchestrator docker containers. @@ -61,43 +43,14 @@ HOST [magma]$ cd orc8r/cloud/docker HOST [magma/orc8r/cloud/docker]$ ./build.py --all ``` -This will build all the docker images for Orchestrator. The `vagrant up` from -the first tab should finish before the image building, so you should switch -to that tab and move on for now. - ## Initial Run -Once `vagrant up` in the first tab finishes: - -### Terminal Tab 1: Build AGW from Source - -We will kick off the initial build of the AGW from source here. - -```bash -HOST [magma/lte/gateway]$ vagrant ssh magma -MAGMA-VM [/home/vagrant]$ cd $MAGMA_ROOT && bazel/scripts/build_and_run_bazelified_agw.sh -``` - -**Note**: If you encounter unexpected errors during this process, try running -`vagrant provision magma` in the host environment for more debugging -information. - -This will take a while (we have a lot of CXX files to build). With 2 extensive -build jobs running, now is a good time to grab a coffee or lunch. The first -build ever from source will take a while, but afterwards, a persistent Bazel -cache and Docker's native layer caching will speed up subsequent builds -significantly. - -You can monitor what happens in the other tab now: - ### Terminal Tab 2: Start Orchestrator Once the Orchestrator build finishes, we can start the development Orchestrator -cloud for the first time. We'll also use this time to register the local -client certificate you'll need to access the local API gateway for your -development stack. +cloud for the first time. -To start Orchestrator (without metrics) is as simple as: +To start Orchestrator (without metrics): ```bash HOST [magma/orc8r/cloud/docker]$ ./run.py @@ -116,19 +69,6 @@ If you want to run everything, including metrics, run: ```bash HOST [magma/orc8r/cloud/docker]$ ./run.py --metrics - -Creating orc8r_alertmanager_1 ... done -Creating orc8r_maria_1 ... done -Creating elasticsearch ... done -Creating orc8r_postgres_1 ... done -Creating orc8r_config-manager_1 ... done -Creating orc8r_test_1 ... done -Creating orc8r_prometheus-cache_1 ... done -Creating orc8r_prometheus_1 ... done -Creating orc8r_kibana_1 ... done -Creating fluentd ... done -Creating orc8r_proxy_1 ... done -Creating orc8r_controller_1 ... done ``` The Orchestrator application containers will bootstrap certificates on startup @@ -174,36 +114,27 @@ Note that your browser may refuse to accept the server certificate from `localhost:9443`. Firefox and Safari will let you override this warning. Chrome will also let you [bypass the warning if you type `thisisunsafe`](https://www.technipages.com/google-chrome-bypass-your-connection-is-not-private-message). -### Connecting Your Local LTE Gateway to Your Local Cloud +### Register Your AGW with Orchestrator -At this point, you will have built all the code in the LTE access gateway and -the Orchestrator cloud. All the services on the LTE access gateway and -orchestrator cloud are running, but your gateway VM isn't yet set up to -communicate with your local cloud. - -We have a fabric command set up to do this: +Register your Docker-based AGW with Orchestrator: ```bash HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ fab register-vm +HOST [magma/lte/gateway]$ fab register-agw ``` -This command will seed your gateway and network on Orchestrator with some -default LTE configuration values and set your gateway VM up to talk to your -local Orchestrator cloud. Wait a minute or 2 for the changes to propagate, -then you can verify that things are working: +Wait a minute or 2 for the changes to propagate, then you can verify that things are working: ```bash -HOST [magma/lte/gateway]$ vagrant ssh magma +HOST [magma/lte/gateway]$ docker exec -it magma_control /bin/bash -MAGMA-VM$ sudo service magma@* stop -MAGMA-VM$ sudo service magma@magmad start -MAGMA-VM$ sudo tail -f /var/log/syslog +MAGMA-CONTROL$ sudo service magma@* stop +MAGMA-CONTROL$ sudo service magma@magmad start +MAGMA-CONTROL$ sudo tail -f /var/log/syslog # After a minute or 2 you should see these messages: Sep 27 22:57:35 magma-dev magmad[6226]: [2018-09-27 22:57:35,550 INFO root] Checkin Successful! Sep 27 22:57:55 magma-dev magmad[6226]: [2018-09-27 22:57:55,684 INFO root] Processing config update g1 -Sep 27 22:57:55 magma-dev control_proxy[6418]: 2018-09-27T22:57:55.683Z [127.0.0.1 -> streamer-controller.magma.test,8443] "POST /magma.Streamer/GetUpdates HTTP/2" 200 7bytes 0.009s ``` ## Using the NMS UI @@ -228,8 +159,8 @@ Note that you will only see a network if you connected your local LTE gateway as Organizations are managed at [host.localhost](https://host.localhost) where you can log in with the same credentials. -**Note**: If you want to test the access gateway VM with a physical eNB and UE, -refer to -the [Connecting a physical eNodeb and UE device to gateway -VM](../lte/dev_notes.md#connecting-a-physical-enodeb-and-ue-to-gateway-vm) -section. +## Additional Resources + +- For detailed AGW Docker deployment, see [AGW Docker deployment guide](../deployment/agw/docker.md) +- For testing LTE features without cloud-based network management, see [S1AP integration tests](../lte/s1ap_tests.md) +- For connecting a physical eNB and UE device, see the [Connecting a physical eNodeb and UE device to gateway](../lte/dev_notes.md#connecting-a-physical-enodeb-and-ue-to-gateway-vm) section. \ No newline at end of file From b8bf1dbf5c6f6f3f4dee327f4b3fcd538736615c Mon Sep 17 00:00:00 2001 From: spirizeon Date: Sun, 3 May 2026 22:56:23 +0530 Subject: [PATCH 2/7] docs: remove Vagrant documentation and add deprecation notice - Removed Vagrant and VirtualBox from prerequisites (macOS and Ubuntu) - Replaced Vagrant-based AGW setup with Docker-based deployment - Added deprecation notice in introduction.md directing users to Docker - Updated quick_start_guide.md to use agw_docker_install.sh - Part of Issue #45: Remove Vagrant Documentation from Magma Documentation Repository See: magma/magma#15754 --- docusaurus/docs/basics/prerequisites.md | 5 +- docusaurus/docs/basics/quick_start_guide.md | 89 +++++--------- readmes/basics/introduction.md | 9 ++ readmes/basics/prerequisites.md | 13 --- readmes/basics/quick_start_guide.md | 121 +++++--------------- 5 files changed, 63 insertions(+), 174 deletions(-) diff --git a/docusaurus/docs/basics/prerequisites.md b/docusaurus/docs/basics/prerequisites.md index a437f5e..85da8e1 100644 --- a/docusaurus/docs/basics/prerequisites.md +++ b/docusaurus/docs/basics/prerequisites.md @@ -15,17 +15,16 @@ Install the following tools: 1. [Docker](https://www.docker.com) and Docker Compose 2. [Homebrew](https://brew.sh/) *only* for MacOS users -3. [VirtualBox](https://www.virtualbox.org/) -3. [Vagrant](https://vagrantup.com) Replace `brew` with your OS-appropriate package manager as necessary: ```bash brew install python3 pip3 install ansible fabric3 jsonpickle requests PyYAML -vagrant plugin install vagrant-vbguest ``` +> **Note**: Vagrant-based development has been deprecated. Please use the Docker-based AGW deployment instead. + If you are on MacOS, you should start Docker for Mac and increase the memory allocation for the Docker engine to at least 4GB (Preferences -> Advanced). diff --git a/docusaurus/docs/basics/quick_start_guide.md b/docusaurus/docs/basics/quick_start_guide.md index 1a9fdc2..2424bb3 100644 --- a/docusaurus/docs/basics/quick_start_guide.md +++ b/docusaurus/docs/basics/quick_start_guide.md @@ -12,36 +12,32 @@ installing Magma for a production deployment. With the [prereqs](prerequisites.md) installed, we can now set up a minimal end-to-end system on your development environment. In this guide, we'll start -by running the LTE access gateway and orchestrator cloud, and then +by running the LTE access gateway (via Docker) and orchestrator cloud, and then register your local access gateway with your local cloud for management. -We will be spinning up a virtual machine and some docker containers for this -full setup, so you'll probably want to do this on a system with at least 8GB -of memory. Our development VM's are in the 192.168.80.0/24 address space, so -make sure that you don't have anything running which hijacks that (e.g. VPN). +> **Note**: Vagrant-based development has been deprecated. Please use the +> Docker-based AGW deployment. See the [AGW Docker deployment guide](../deployment/agw/docker.md) +> for the latest instructions. -In the following steps, note the prefix in terminal commands. `HOST` means to -run the indicated command on your host machine, and `MAGMA-VM` on the `magma` -vagrant machine under `lte/gateway`. +We will be spinning up docker containers for this full setup, so you'll +probably want to do this on a system with at least 8GB of memory. ## Provisioning the environment -Go ahead and open up 2 fresh terminal tabs. Start in +Go ahead and open up 2 fresh terminal tabs. -### Terminal Tab 1: Provision the AGW VM +### Terminal Tab 1: Provision the AGW (Docker) -The development environment virtualizes the access gateway so you don't need -any production hardware on hand to test an end-to-end setup. -We'll be setting up the LTE AGW VM in this tab. +The development environment can use Docker to run the Access Gateway. See the +[AGW Docker deployment](../deployment/agw/docker.md) for detailed instructions. + +For quick setup: ```bash -HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ vagrant up magma +HOST [magma]$ cd lte/gateway/deploy +HOST [magma/lte/gateway/deploy]$ ./agw_docker_install.sh ``` -This will take a few minutes to spin up the VM. While that runs, switch over -to... - ### Terminal Tab 2: Build Orchestrator Here, we'll be building the Orchestrator docker containers. @@ -51,38 +47,12 @@ HOST [magma]$ cd orc8r/cloud/docker HOST [magma/orc8r/cloud/docker]$ ./build.py -a ``` -This will build all the docker images for Orchestrator. The `vagrant up` from -the first tab should finish before the image building, so you should switch -to that tab and move on for now. - ## Initial Run -Once `vagrant up` in the first tab finishes: - -### Terminal Tab 1: Build AGW from Source - -We will kick off the initial build of the AGW from source here. - -```bash -HOST [magma/lte/gateway]$ vagrant ssh magma -MAGMA-VM [/home/vagrant]$ cd magma/lte/gateway -MAGMA-VM [/home/vagrant/magma/lte/gateway]$ make run -``` - -This will take a while (we have a lot of CXX files to build). With 2 extensive -build jobs running, now is a good time to grab a coffee or lunch. The first -build ever from source will take a while, but afterwards, a persistent ccache -and Docker's native layer caching will speed up subsequent builds -significantly. - -You can monitor what happens in the other tab now: - ### Terminal Tab 2: Start Orchestrator Once the Orchestrator build finishes, we can start the development Orchestrator -cloud for the first time. We'll also use this time to register the local -client certificate you'll need to access the local API gateway for your -development stack. +cloud for the first time. Starting Orchestrator is as simple as: @@ -123,31 +93,23 @@ installed client certificates. See [here](https://support.globalsign.com/custome for instructions. If you use Chrome or Safari, you may have to restart the browser before the certificate can be used. -### Connecting Your Local LTE Gateway to Your Local Cloud +### Register Your AGW with Orchestrator -At this point, you will have built all the code in the LTE access gateway and -the Orchestrator cloud. All the services on the LTE access gateway and -orchestrator cloud are running, but your gateway VM isn't yet set up to -communicate with your local cloud. - -We have a fabric command set up to do this: +Register your Docker-based AGW with Orchestrator: ```bash HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ fab -f dev_tools.py register_vm +HOST [magma/lte/gateway]$ fab -f dev_tools.py register_agw ``` -This command will seed your gateway and network on Orchestrator with some -default LTE configuration values and set your gateway VM up to talk to your -local Orchestrator cloud. Wait a minute or 2 for the changes to propagate, -then you can verify that things are working: +Wait a minute or 2 for the changes to propagate, then you can verify that things are working: ```bash -HOST [magma/lte/gateway]$ vagrant ssh magma +HOST [magma/lte/gateway]$ docker exec -it magma_control /bin/bash -MAGMA-VM$ sudo service magma@* stop -MAGMA-VM$ sudo service magma@magmad restart -MAGMA-VM$ sudo tail -f /var/log/syslog +MAGMA-CONTROL$ sudo service magma@* stop +MAGMA-CONTROL$ sudo service magma@magmad restart +MAGMA-CONTROL$ sudo tail -f /var/log/syslog # After a minute or 2 you should see these messages: Sep 27 22:57:35 magma-dev magmad[6226]: [2018-09-27 22:57:35,550 INFO root] Checkin Successful! @@ -172,6 +134,7 @@ After this, you will be able to access the UI by visiting and password `password1234`. If you see Gateway Error 502, don't worry, the NMS can take upto 60 seconds to finish starting up. +## Additional Resources - - +- For detailed AGW Docker deployment, see [AGW Docker deployment guide](../deployment/agw/docker.md) +- For testing LTE features without cloud-based network management, see [S1AP integration tests](../lte/s1ap_tests.md) \ No newline at end of file diff --git a/readmes/basics/introduction.md b/readmes/basics/introduction.md index 055a8f0..d1e408d 100644 --- a/readmes/basics/introduction.md +++ b/readmes/basics/introduction.md @@ -64,6 +64,15 @@ Magma leverages a variety of modern technologies to implement its solutions: - The main programming languages used in development. - Multiple language equals multiple opportunities to contribute. +## Deployment Methods + +Magma supports multiple deployment methods for the Access Gateway (AGW): + +- **Docker-based AGW** (Recommended): The modern, containerized approach for development and production. See the [AGW Docker deployment guide](./deployment/agw/docker.md). +- **Bare Metal**: For production deployments on physical hardware. + +> **Deprecation Notice**: Vagrant-based AGW deployment has been **deprecated** and will be removed in a future release. Please migrate to the Docker-based deployment method. + ## Community Join the [Magma Slack channel](https://join.slack.com/t/magmacore/shared_invite/zt-g76zkofr-g6~jYiS3KRzC9qhAISUC2A) and interact with our active community. diff --git a/readmes/basics/prerequisites.md b/readmes/basics/prerequisites.md index 872ce1d..4a549fd 100644 --- a/readmes/basics/prerequisites.md +++ b/readmes/basics/prerequisites.md @@ -27,8 +27,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e 1. [Docker and Docker Compose](https://docs.docker.com/desktop/install/mac-install/) 2. [Homebrew](https://brew.sh/) - 3. [VirtualBox](https://www.virtualbox.org/) - 4. [Vagrant](https://vagrantup.com) ```bash brew install go@1.20 pyenv @@ -42,7 +40,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e pyenv install 3.8.10 pyenv global 3.8.10 pip3 install ansible fabric jsonpickle requests PyYAML - vagrant plugin install vagrant-vbguest vagrant-disksize vagrant-reload ``` **Note**: In the case where installation of `fabric` through pip was unsuccessful, @@ -59,8 +56,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e 1. Install the following tools 1. [Docker and Docker Compose](https://docs.docker.com/engine/install/ubuntu/) - 2. [VirtualBox](https://www.virtualbox.org/wiki/Linux_Downloads) - 3. [Vagrant](https://www.vagrantup.com/downloads) 2. Install golang version 1.20.1. 1. Download the tar file. @@ -147,14 +142,6 @@ Development can occur from multiple OS's, where **macOS** and **Ubuntu** are **e pip3 install ansible fabric jsonpickle requests PyYAML ``` -5. Install `vagrant` necessary plugin. - - ```bash - vagrant plugin install vagrant-vbguest vagrant-disksize vagrant-reload - ``` - - Make sure `virtualbox` is the default provider for `vagrant` by adding the following line to your `.bashrc` (or equivalent) and restart your shell: `export VAGRANT_DEFAULT_PROVIDER="virtualbox"`. - ## Downloading Magma You can find Magma code on [Github](https://github.com/magma/magma). diff --git a/readmes/basics/quick_start_guide.md b/readmes/basics/quick_start_guide.md index 05cef95..cc903ba 100644 --- a/readmes/basics/quick_start_guide.md +++ b/readmes/basics/quick_start_guide.md @@ -11,47 +11,29 @@ installing Magma for a production deployment. With the [prereqs](prerequisites.md) installed, we can now set up a minimal end-to-end system on your development environment. In this guide, we'll start -by running the LTE access gateway and orchestrator cloud, and then +by running the LTE access gateway (via Docker) and orchestrator cloud, and then register your local access gateway with your local cloud for management. -We will be spinning up a virtual machine and some docker containers for this -full setup, so you'll probably want to do this on a system with at least 8GB -of memory. Our development VM's are in the 192.168.60.0/24, 192.168.128.0/24 and -192.168.129.0/24 address spaces, so make sure that you don't have anything -running which hijacks those (e.g. VPN). - -In the following steps, note the prefix in terminal commands. `HOST` means to -run the indicated command on your host machine, and `MAGMA-VM` on the `magma` -vagrant machine under `lte/gateway`. +> **Note**: Vagrant-based development has been deprecated. Please use the +> Docker-based AGW deployment. See the [AGW Docker deployment guide](../deployment/agw/docker.md) +> for the latest instructions. ## Provisioning the environment -Go ahead and open up 2 fresh terminal tabs. Start in +Go ahead and open up 2 fresh terminal tabs. -### Terminal Tab 1: Provision the AGW VM +### Terminal Tab 1: Provision the AGW (Docker) -The development environment virtualizes the access gateway, so you don't need -any production hardware on hand to test an end-to-end setup. -We'll be setting up the LTE AGW VM in this tab. +The development environment can use Docker to run the Access Gateway. See the +[AGW Docker deployment](../deployment/agw/docker.md) for detailed instructions. -You need to make sure that your local network setup is correct for the VM to -start properly. Especially the entries `* 192.168.0.0/16` and `* 3001::/64` must exist in your -`/etc/vbox/networks.conf`. +For quick setup: ```bash -HOST [magma]$ echo "* 192.168.0.0/16" | sudo tee -a /etc/vbox/networks.conf -HOST [magma]$ echo "* 3001::/64" | sudo tee -a /etc/vbox/networks.conf -HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ vagrant up magma +HOST [magma]$ cd lte/gateway/deploy +HOST [magma/lte/gateway/deploy]$ ./agw_docker_install.sh ``` -This will take a few minutes to spin up the VM. While that runs, switch over -to... - -**Note**: If you are looking to test/develop the LTE features of AGW, without -cloud based network management, you can skip the rest of this guide and try the -[S1AP integration tests](../lte/s1ap_tests.md) now. - ### Terminal Tab 2: Build Orchestrator Here, we'll be building the Orchestrator docker containers. @@ -61,43 +43,14 @@ HOST [magma]$ cd orc8r/cloud/docker HOST [magma/orc8r/cloud/docker]$ ./build.py --all ``` -This will build all the docker images for Orchestrator. The `vagrant up` from -the first tab should finish before the image building, so you should switch -to that tab and move on for now. - ## Initial Run -Once `vagrant up` in the first tab finishes: - -### Terminal Tab 1: Build AGW from Source - -We will kick off the initial build of the AGW from source here. - -```bash -HOST [magma/lte/gateway]$ vagrant ssh magma -MAGMA-VM [/home/vagrant]$ cd $MAGMA_ROOT && bazel/scripts/build_and_run_bazelified_agw.sh -``` - -**Note**: If you encounter unexpected errors during this process, try running -`vagrant provision magma` in the host environment for more debugging -information. - -This will take a while (we have a lot of CXX files to build). With 2 extensive -build jobs running, now is a good time to grab a coffee or lunch. The first -build ever from source will take a while, but afterwards, a persistent Bazel -cache and Docker's native layer caching will speed up subsequent builds -significantly. - -You can monitor what happens in the other tab now: - ### Terminal Tab 2: Start Orchestrator Once the Orchestrator build finishes, we can start the development Orchestrator -cloud for the first time. We'll also use this time to register the local -client certificate you'll need to access the local API gateway for your -development stack. +cloud for the first time. -To start Orchestrator (without metrics) is as simple as: +To start Orchestrator (without metrics): ```bash HOST [magma/orc8r/cloud/docker]$ ./run.py @@ -116,19 +69,6 @@ If you want to run everything, including metrics, run: ```bash HOST [magma/orc8r/cloud/docker]$ ./run.py --metrics - -Creating orc8r_alertmanager_1 ... done -Creating orc8r_maria_1 ... done -Creating elasticsearch ... done -Creating orc8r_postgres_1 ... done -Creating orc8r_config-manager_1 ... done -Creating orc8r_test_1 ... done -Creating orc8r_prometheus-cache_1 ... done -Creating orc8r_prometheus_1 ... done -Creating orc8r_kibana_1 ... done -Creating fluentd ... done -Creating orc8r_proxy_1 ... done -Creating orc8r_controller_1 ... done ``` The Orchestrator application containers will bootstrap certificates on startup @@ -174,36 +114,27 @@ Note that your browser may refuse to accept the server certificate from `localhost:9443`. Firefox and Safari will let you override this warning. Chrome will also let you [bypass the warning if you type `thisisunsafe`](https://www.technipages.com/google-chrome-bypass-your-connection-is-not-private-message). -### Connecting Your Local LTE Gateway to Your Local Cloud +### Register Your AGW with Orchestrator -At this point, you will have built all the code in the LTE access gateway and -the Orchestrator cloud. All the services on the LTE access gateway and -orchestrator cloud are running, but your gateway VM isn't yet set up to -communicate with your local cloud. - -We have a fabric command set up to do this: +Register your Docker-based AGW with Orchestrator: ```bash HOST [magma]$ cd lte/gateway -HOST [magma/lte/gateway]$ fab register-vm +HOST [magma/lte/gateway]$ fab register-agw ``` -This command will seed your gateway and network on Orchestrator with some -default LTE configuration values and set your gateway VM up to talk to your -local Orchestrator cloud. Wait a minute or 2 for the changes to propagate, -then you can verify that things are working: +Wait a minute or 2 for the changes to propagate, then you can verify that things are working: ```bash -HOST [magma/lte/gateway]$ vagrant ssh magma +HOST [magma/lte/gateway]$ docker exec -it magma_control /bin/bash -MAGMA-VM$ sudo service magma@* stop -MAGMA-VM$ sudo service magma@magmad start -MAGMA-VM$ sudo tail -f /var/log/syslog +MAGMA-CONTROL$ sudo service magma@* stop +MAGMA-CONTROL$ sudo service magma@magmad start +MAGMA-CONTROL$ sudo tail -f /var/log/syslog # After a minute or 2 you should see these messages: Sep 27 22:57:35 magma-dev magmad[6226]: [2018-09-27 22:57:35,550 INFO root] Checkin Successful! Sep 27 22:57:55 magma-dev magmad[6226]: [2018-09-27 22:57:55,684 INFO root] Processing config update g1 -Sep 27 22:57:55 magma-dev control_proxy[6418]: 2018-09-27T22:57:55.683Z [127.0.0.1 -> streamer-controller.magma.test,8443] "POST /magma.Streamer/GetUpdates HTTP/2" 200 7bytes 0.009s ``` ## Using the NMS UI @@ -228,8 +159,8 @@ Note that you will only see a network if you connected your local LTE gateway as Organizations are managed at [host.localhost](https://host.localhost) where you can log in with the same credentials. -**Note**: If you want to test the access gateway VM with a physical eNB and UE, -refer to -the [Connecting a physical eNodeb and UE device to gateway -VM](../lte/dev_notes.md#connecting-a-physical-enodeb-and-ue-to-gateway-vm) -section. +## Additional Resources + +- For detailed AGW Docker deployment, see [AGW Docker deployment guide](../deployment/agw/docker.md) +- For testing LTE features without cloud-based network management, see [S1AP integration tests](../lte/s1ap_tests.md) +- For connecting a physical eNB and UE device, see the [Connecting a physical eNodeb and UE device to gateway](../lte/dev_notes.md#connecting-a-physical-enodeb-and-ue-to-gateway-vm) section. \ No newline at end of file From 04847bf11f181c9d9303700370c15b2935fedb57 Mon Sep 17 00:00:00 2001 From: spirizeon Date: Sun, 3 May 2026 23:01:53 +0530 Subject: [PATCH 3/7] fix: update link path and add migration pointer to deprecation notice - Fixed relative link from ./deployment/agw/docker.md to ../deployment/agw/docker.md - Added migration guide reference to deprecation notice pointing to issue #15754 --- readmes/basics/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readmes/basics/introduction.md b/readmes/basics/introduction.md index d1e408d..bb27464 100644 --- a/readmes/basics/introduction.md +++ b/readmes/basics/introduction.md @@ -68,10 +68,10 @@ Magma leverages a variety of modern technologies to implement its solutions: Magma supports multiple deployment methods for the Access Gateway (AGW): -- **Docker-based AGW** (Recommended): The modern, containerized approach for development and production. See the [AGW Docker deployment guide](./deployment/agw/docker.md). +- **Docker-based AGW** (Recommended): The modern, containerized approach for development and production. See the [AGW Docker deployment guide](../deployment/agw/docker.md). - **Bare Metal**: For production deployments on physical hardware. -> **Deprecation Notice**: Vagrant-based AGW deployment has been **deprecated** and will be removed in a future release. Please migrate to the Docker-based deployment method. +> **Deprecation Notice**: Vagrant-based AGW deployment has been **deprecated** and will be removed in a future release. Please migrate to the Docker-based deployment method. See the Vagrant-to-Docker migration guide in issue [#15754](https://github.com/magma/magma/issues/15754) for detailed instructions. ## Community From 7d814d7a2a6bf3bdd25f155816fe3ad984473c18 Mon Sep 17 00:00:00 2001 From: spirizeon Date: Sun, 3 May 2026 23:09:50 +0530 Subject: [PATCH 4/7] docs: continue removing Vagrant documentation - Updated docusaurus/docs/lte/setup.md to use Docker instead of Vagrant - Updated readmes/lte/readme_agw.md to use docker exec instead of vagrant ssh - Updated readmes/lte/build_install_magma_pkg_in_agw.md to use Docker - Updated readmes/lte/dev_unit_testing.md to use Docker containers Part of Issue #45: Remove Vagrant Documentation --- docusaurus/docs/lte/setup.md | 37 ++++++++++--------- readmes/lte/build_install_magma_pkg_in_agw.md | 15 +++++--- readmes/lte/dev_unit_testing.md | 12 +++--- readmes/lte/readme_agw.md | 6 +-- 4 files changed, 39 insertions(+), 31 deletions(-) diff --git a/docusaurus/docs/lte/setup.md b/docusaurus/docs/lte/setup.md index c257ea5..b5ed722 100644 --- a/docusaurus/docs/lte/setup.md +++ b/docusaurus/docs/lte/setup.md @@ -1,33 +1,34 @@ --- id: version-1.0.0-setup -title: AGW Setup (With Vagrant) -sidebar_label: Setup (With Vagrant) +title: AGW Setup +sidebar_label: Setup hide_title: true original_id: setup --- -# Access Gateway Setup (With Vagrant) -### Prerequisites -To develop and manage a Magma VM, you must have the following applications installed locally: +# Access Gateway Setup -* Virtualbox -* Vagrant -* Ansible +> **Note**: Vagrant-based AGW setup has been deprecated. Please use Docker-based deployment. -### Steps +### Prerequisites -To bring up an Access Gateway (AGW) VM using Vagrant: +To develop and manage a Magma AGW using Docker, you must have the following installed: -* Run the following command: +- Docker and Docker Compose +- Ansible (for configuration) -``HOST:magma/lte/gateway USER$ vagrant up magma`` +### Steps -Vagrant will bring up the VM, then Ansible will provision the VM. +To bring up an Access Gateway (AGW) using Docker, follow the [AGW Docker deployment guide](../deployment/agw/docker.md). +Quick start: -* Once the Access Gateway VM is up and provisioned, run the following commands: +```bash +HOST [magma/lte/gateway]$ cd lte/gateway/deploy +HOST [magma/lte/gateway/deploy]$ ./agw_docker_install.sh +``` -``HOST:magma/lte/gateway USER$ vagrant ssh magma``

-``AGW:~ USER$ cd magma/lte/gateway``

-``AGW:~/magma/lte/gateway USER$ make run`` +Once the Access Gateway is running successfully, proceed to attaching the eNodeB. -Once the Access Gateway VM is running successfully, proceed to attaching the eNodeB. +For more details, see: +- [Quick Start Guide](../basics/quick_start_guide.md) +- [AGW Docker Deployment](../deployment/agw/docker.md) \ No newline at end of file diff --git a/readmes/lte/build_install_magma_pkg_in_agw.md b/readmes/lte/build_install_magma_pkg_in_agw.md index fdfe9a6..b6ef8ae 100644 --- a/readmes/lte/build_install_magma_pkg_in_agw.md +++ b/readmes/lte/build_install_magma_pkg_in_agw.md @@ -28,16 +28,21 @@ Note that the following is supported starting with magma v1.9. For older version Make sure you have installed all the tools specified in the [prerequisites](https://magma.github.io/magma/docs/basics/prerequisites#prerequisites) 3. **Build and create deb package**. - To build an AGW package spin up a vagrant machine and then build and create a deb package. + To build an AGW package, use the Docker-based AGW environment or a bare metal machine. - From `$MAGMA_ROOT/lte/gateway` on your host machine run: + From `$MAGMA_ROOT/lte/gateway` on your host machine, you can use Docker: ```bash - vagrant up magma - vagrant ssh magma + cd lte/gateway/deploy + ./agw_docker_install.sh + docker exec -it magma_control /bin/bash ``` - In the VM from `$MAGMA_ROOT` run: + In the container from `$MAGMA_ROOT` run: + + ```bash + bazel run //lte/gateway/release:release_build --config=production + ``` ```bash bazel run //lte/gateway/release:release_build --config=production diff --git a/readmes/lte/dev_unit_testing.md b/readmes/lte/dev_unit_testing.md index fc473be..781e28d 100644 --- a/readmes/lte/dev_unit_testing.md +++ b/readmes/lte/dev_unit_testing.md @@ -10,14 +10,16 @@ This guide covers tips for quickly validating AGW changes. ## Run all unit tests -Unit testing for AGW can be done either inside the magma-dev VM, or inside the devcontainer or bazel-base Docker containers. +Unit testing for AGW can be done either inside the Docker-based AGW container, the devcontainer, or bazel-base Docker containers. -To SSH into the magma-dev VM, run +> **Note**: Vagrant-based testing has been deprecated. Please use Docker containers. + +To use Docker-based AGW, run: ```bash -[HOST] cd $MAGMA_ROOT/lte/gateway -[HOST] vagrant up magma -[HOST] vagrant ssh magma +[HOST] cd $MAGMA_ROOT/lte/gateway/deploy +[HOST] ./agw_docker_install.sh +[HOST] docker exec -it magma_control /bin/bash ``` To start the devcontainer, run diff --git a/readmes/lte/readme_agw.md b/readmes/lte/readme_agw.md index 0acc455..9690aa1 100644 --- a/readmes/lte/readme_agw.md +++ b/readmes/lte/readme_agw.md @@ -126,11 +126,11 @@ magma/lte/gateway/python/scripts. These are: 7. Enodebd: enodebd_cli.py 8. State Tracing: state_cli.py -Each of these CLIs can be used in the gateway VM: +Each of these CLIs can be used in the gateway container: ```bash -vagrant@magma-dev:~$ magtivate -(python) vagrant@magma-dev:~$ enodebd_cli.py -h +MAGMA-CONTROL$ docker exec -it magma_control /bin/bash +MAGMA-CONTROL$ enodebd_cli.py -h usage: enodebd_cli.py [-h] {get_parameter,set_parameter,config_enodeb,reboot_enodeb,get_status} From aae3d1a3cd7f52c51cfb823bce5efd0facc7926e Mon Sep 17 00:00:00 2001 From: spirizeon Date: Sun, 3 May 2026 23:10:10 +0530 Subject: [PATCH 5/7] docs: continue removing Vagrant documentation from additional files - Updated docusaurus/docs/cwf/setup.md to use Docker instead of Vagrant - Added deprecation notice to docusaurus/docs/lte/s1ap_tests.md - Added deprecation notice to readmes/feg/s1ap_federated_tests.md - Updated architecture section to remove Vagrant mentions Part of Issue #45: Remove Vagrant Documentation --- docusaurus/docs/cwf/setup.md | 39 +++++++++++++---------------- docusaurus/docs/lte/s1ap_tests.md | 7 ++++-- readmes/feg/s1ap_federated_tests.md | 4 ++- 3 files changed, 26 insertions(+), 24 deletions(-) diff --git a/docusaurus/docs/cwf/setup.md b/docusaurus/docs/cwf/setup.md index 3ec24c7..da45408 100644 --- a/docusaurus/docs/cwf/setup.md +++ b/docusaurus/docs/cwf/setup.md @@ -1,35 +1,32 @@ --- id: version-1.0.0-setup -title: CWAG Setup (With Vagrant) -sidebar_label: Setup (With Vagrant) +title: CWAG Setup +sidebar_label: Setup hide_title: true original_id: setup --- -# CWF Access Gateway Setup (With Vagrant) -### Prerequisites -To develop and manage a Magma VM, you must have the following applications installed locally: - -* Virtualbox -* Vagrant -* Ansible +# Carrier Wifi Access Gateway (CWAG) Setup -### Steps +> **Note**: Vagrant-based CWAG setup has been deprecated. Please use Docker-based deployment. -To bring up a Wifi Access Gateway (CWAG) VM using Vagrant: +### Prerequisites -* Run the following command: +To develop and manage a Magma CWAG using Docker, you must have the following installed: -``HOST:magma/cwf/gateway USER$ vagrant up cwag`` +- Docker and Docker Compose +- Ansible (for configuration) -Vagrant will bring up the VM, then Ansible will provision the VM. +### Steps +To bring up a Carrier Wifi Access Gateway (CWAG) using Docker, follow the [AGW Docker deployment guide](../deployment/agw/docker.md). -* Once the CWAG VM is up and provisioned, run the following commands: +Quick start: -``HOST:magma/cwf/gateway USER$ vagrant ssh cwag``

-``AGW:~ USER$ cd magma/cwf/gateway/docker``

-``AGW:~/magma/cwf/gateway/docker USER$ docker-compose build --parallel`` -``AGW:~/magma/cwf/gateway/docker USER$ docker-compose up -d`` +```bash +HOST [magma/cwf/gateway]$ cd cwf/gateway/deploy +HOST [magma/cwf/gateway/deploy]$ ./agw_docker_install.sh +``` -After this, all the CWAG docker containers should have been brought up -successfully. +For more details, see: +- [Quick Start Guide](../basics/quick_start_guide.md) +- [AGW Docker Deployment](../deployment/agw/docker.md) \ No newline at end of file diff --git a/docusaurus/docs/lte/s1ap_tests.md b/docusaurus/docs/lte/s1ap_tests.md index 6afab66..f1c5446 100644 --- a/docusaurus/docs/lte/s1ap_tests.md +++ b/docusaurus/docs/lte/s1ap_tests.md @@ -5,9 +5,12 @@ hide_title: true original_id: s1ap_tests --- # S1AP Integration Tests -Current testing workflow for VM-only S1AP integration tests. We cover gateway-only tests, cloud-included tests, and some general notes. -Our VM-only tests use 2 to 4 Vagrant-managed VMs hosted on the local device (laptop): +> **Note**: Vagrant-based testing has been deprecated. Docker-based AGW deployment is now recommended for testing. + +Current testing workflow for S1AP integration tests. We cover gateway-only tests, cloud-included tests, and some general notes. + +For VM-based testing (deprecated), our tests use 2 to 4 Vagrant-managed VMs: - *magma*, i.e. magma-dev or gateway - *magma_test*, i.e. s1ap_tester diff --git a/readmes/feg/s1ap_federated_tests.md b/readmes/feg/s1ap_federated_tests.md index c23ec77..da8ea32 100644 --- a/readmes/feg/s1ap_federated_tests.md +++ b/readmes/feg/s1ap_federated_tests.md @@ -6,6 +6,8 @@ hide_title: true # S1AP Federated Integration Tests +> **Note**: Vagrant-based testing has been deprecated. Docker-based deployment is now recommended. + The S1AP Integration Test only tests the AGW. The objective of the **S1AP Federated Integration Tests** is to provide a test platform to run Magma with all of its components. That is, end-to-end tests with all @@ -26,7 +28,7 @@ graph LR; AGW ---|data| Z[[magma_trfserver]]; ``` -The services will run either on Vagrant VMs or on Docker: +The services will run on Docker: | Services | Vagrant VM | Docker | |-------------------|:---------------:|:---------:| From 503982263e29e89be642ae136cc74f5e6646d3ad Mon Sep 17 00:00:00 2001 From: spirizeon Date: Sun, 3 May 2026 23:27:54 +0530 Subject: [PATCH 6/7] fix: align Vagrant removal with Docker commands and fix inconsistencies - docusaurus/docs/lte/setup.md: Fixed cd path (cd deploy instead of cd lte/gateway/deploy) - readmes/lte/build_install_magma_pkg_in_agw.md: Removed duplicate bazel command, changed VM to container - readmes/lte/dev_unit_testing.md: Changed VM to CONTAINER in test/format sections - readmes/orc8r/dev_gateway_registration.md: Updated paths for Docker instead of Vagrant - docusaurus/docs/lte/README_AGW.md: Updated CLI example for Docker - readmes/bazel/agw_with_bazel.md: Added deprecation notes for Vagrant VMs Part of Issue #45: Remove Vagrant Documentation --- docusaurus/docs/lte/README_AGW.md | 8 +++++--- docusaurus/docs/lte/setup.md | 2 +- readmes/bazel/agw_with_bazel.md | 12 +++++++----- readmes/lte/build_install_magma_pkg_in_agw.md | 6 +----- readmes/lte/dev_unit_testing.md | 12 ++++++------ readmes/orc8r/dev_gateway_registration.md | 8 ++++++-- 6 files changed, 26 insertions(+), 22 deletions(-) diff --git a/docusaurus/docs/lte/README_AGW.md b/docusaurus/docs/lte/README_AGW.md index 8d2b29c..fe87650 100644 --- a/docusaurus/docs/lte/README_AGW.md +++ b/docusaurus/docs/lte/README_AGW.md @@ -114,11 +114,11 @@ magma/lte/gateway/python/scripts. These are: 6. Subscriberdb: subscriber_cli.py 7. Enodebd: enodebd_cli.py -Each of these CLIs can be used in the gateway VM: +Each of these CLIs can be used in the Docker container: ```bash -vagrant@magma-dev:~$ magtivate -(python) vagrant@magma-dev:~$ enodebd_cli.py -h +MAGMA-CONTROL$ docker exec -it magma_control /bin/bash +MAGMA-CONTROL$ enodebd_cli.py -h usage: enodebd_cli.py [-h] {get_parameter,set_parameter,config_enodeb,reboot_enodeb,get_status} @@ -137,3 +137,5 @@ subcommands: reboot_enodeb Reboot eNodeB get_status Get eNodeB status ``` + +> **Note**: For Vagrant-based development (deprecated), use `vagrant@magma-dev:~$ magtivate` diff --git a/docusaurus/docs/lte/setup.md b/docusaurus/docs/lte/setup.md index b5ed722..1d614ac 100644 --- a/docusaurus/docs/lte/setup.md +++ b/docusaurus/docs/lte/setup.md @@ -23,7 +23,7 @@ To bring up an Access Gateway (AGW) using Docker, follow the [AGW Docker deploym Quick start: ```bash -HOST [magma/lte/gateway]$ cd lte/gateway/deploy +HOST [magma/lte/gateway]$ cd deploy HOST [magma/lte/gateway/deploy]$ ./agw_docker_install.sh ``` diff --git a/readmes/bazel/agw_with_bazel.md b/readmes/bazel/agw_with_bazel.md index c758c50..fc6c9e6 100644 --- a/readmes/bazel/agw_with_bazel.md +++ b/readmes/bazel/agw_with_bazel.md @@ -110,11 +110,13 @@ The following Magma environments currently support Bazel: - The devcontainer is defined in `.devcontainer/Dockerfile` and meant for local development. The docker image is published at [`ghcr.io/magma/magma/devcontainer:latest`](https://github.com/magma/magma/pkgs/container/magma%2Fdevcontainer). - **Bazel-base** - The Bazel-base docker container is a minimal container where only required dependencies are installed. While this image is mainly intended to be used in CI, it can also be useful for local testing. The Bazel-base image is defined in `.devcontainer/bazel-base/Dockerfile` and published at [`ghcr.io/magma/magma/bazel-base:latest`](https://github.com/magma/magma/pkgs/container/magma%2Fbazel-base). -- Vagrant VMs - - **magma-dev** - - The magma-dev virtual machine is intended for local development and for extended testing in CI. It can be used to run the Magma AGW services, as well as e.g. the [Python sudo tests](#python-sudo-tests). - - **magma-test** - - The magma-test virtual machine is used in CI to run the [LTE integration tests](#lte-integration-tests). + - Vagrant VMs (Deprecated) + - **magma-dev** + - The magma-dev virtual machine is intended for local development and for extended testing in CI. It can be used to run the Magma AGW services, as well as e.g. the [Python sudo tests](#python-sudo-tests). + - > **Note**: Vagrant-based development has been deprecated. Use Docker-based AGW instead. + - **magma-test** + - The magma-test virtual machine is used in CI to run the [LTE integration tests](#lte-integration-tests). + - > **Note**: Vagrant-based testing has been deprecated. ### Caching diff --git a/readmes/lte/build_install_magma_pkg_in_agw.md b/readmes/lte/build_install_magma_pkg_in_agw.md index b6ef8ae..184f346 100644 --- a/readmes/lte/build_install_magma_pkg_in_agw.md +++ b/readmes/lte/build_install_magma_pkg_in_agw.md @@ -44,10 +44,6 @@ Note that the following is supported starting with magma v1.9. For older version bazel run //lte/gateway/release:release_build --config=production ``` - ```bash - bazel run //lte/gateway/release:release_build --config=production - ``` - To create a package for development or testing, run ```bash @@ -57,7 +53,7 @@ Note that the following is supported starting with magma v1.9. For older version Omitting the `--config=production` flag will compile all C++ services with `Debug` compiler flags and enable ASAN. This is recommended for testing only as it will impact performance. In contrast, the production package has C++ services built with `RelWithDebInfo` compiler flags. 4. **Locate the packages**. - Once the above command finished you can find the packages inside the VM: + Once the above command finished you can find the packages inside the container: ```bash cd /tmp/packages diff --git a/readmes/lte/dev_unit_testing.md b/readmes/lte/dev_unit_testing.md index 781e28d..eac5a60 100644 --- a/readmes/lte/dev_unit_testing.md +++ b/readmes/lte/dev_unit_testing.md @@ -77,11 +77,11 @@ bazel test //orc8r/gateway/c/...:* //lte/gateway/c/...:* # to test all C/C++ tar ### Test Go AGW services We have several Go implementations of AGW services that live in `orc8r/gateway/go`. -To test any changes, run the following from inside the magma-dev VM +To test any changes, run the following from inside the Docker container ```bash -[VM] cd magma/orc8r/gateway/go -[VM] go test ./... +[CONTAINER] cd magma/orc8r/gateway/go +[CONTAINER] go test ./... ``` ## Format AGW @@ -110,11 +110,11 @@ cd $MAGMA/lte/gateway/python ### Format C/C++ -To run formatting for each C/C++ service, run the following from inside the magma-dev VM +To run formatting for each C/C++ service, run the following from inside the Docker container ```bash -[VM] cd magma/dev_tools -[VM] ./clang_format.sh +[CONTAINER] cd magma/dev_tools +[CONTAINER] ./clang_format.sh ``` #### Apply IWYU diff --git a/readmes/orc8r/dev_gateway_registration.md b/readmes/orc8r/dev_gateway_registration.md index 8982a8d..cf06589 100644 --- a/readmes/orc8r/dev_gateway_registration.md +++ b/readmes/orc8r/dev_gateway_registration.md @@ -41,8 +41,11 @@ The control proxy must have `\n` characters as line breaks. Here is a sample req The registration token expires every 30 minutes and automatically refreshes every time the operator fetches this unregistered gateway. 2. The operator runs the `register.py` script at the gateway with the registration token and its Orc8r's domain name. + > **Note**: Vagrant-based AGW has been deprecated. Please use Docker-based AGW deployment. + ```shell - MAGMA-VM [/home/vagrant]$ sudo /home/vagrant/build/python/bin/python3 ~/magma/orc8r/gateway/python/scripts/register.py [-h] [--ca-file CA_FILE] [--cloud-port CLOUD_PORT] [--no-control-proxy] DOMAIN_NAME REGISTRATION_TOKEN + MAGMA-CONTROL$ docker exec -it magma_control /bin/bash + MAGMA-CONTROL$ sudo /opt/magma/bin/python3 /opt/magma/orc8r/gateway/python/scripts/register.py [-h] [--ca-file CA_FILE] [--cloud-port CLOUD_PORT] [--no-control-proxy] DOMAIN_NAME REGISTRATION_TOKEN ``` The operator can optionally set the root CA file with the `--ca-file CA_FILE` flag or disable writing to the control proxy file with the `--no-control-proxy` flag. @@ -50,7 +53,8 @@ The control proxy must have `\n` characters as line breaks. Here is a sample req For example, in a testing environment with the `rootCA.pem` and `control_proxy.yml` configured, the operator could run ```shell - MAGMA-VM [/home/vagrant]$ sudo /home/vagrant/build/python/bin/python3 ~/magma/orc8r/gateway/python/scripts/register.py magma.test reg_t5S4zjhD0tXRTmkYKQoN91FmWnQSK2 --cloud-port 7444 --no-control-proxy + MAGMA-CONTROL$ docker exec -it magma_control /bin/bash + MAGMA-CONTROL$ sudo /opt/magma/bin/python3 /opt/magma/orc8r/gateway/python/scripts/register.py magma.test reg_t5S4zjhD0tXRTmkYKQoN91FmWnQSK2 --cloud-port 7444 --no-control-proxy ``` Upon success, the script will print the gateway information that was registered and run `checkin_cli.py` automatically. Below is an example of the output of a successful register attempt. From 022363518d712850220c598a6afc6b339da734e5 Mon Sep 17 00:00:00 2001 From: spirizeon Date: Tue, 5 May 2026 02:11:04 +0530 Subject: [PATCH 7/7] fix: address PR review feedback - remove unnecessary deprecation notices - Reverted changes to docusaurus/docs/ (keep only readmes/ changes) - Removed redundant deprecation notices from agw_with_bazel.md, s1ap_federated_tests.md, dev_unit_testing.md, dev_gateway_registration.md - Updated VM references in quick_start_guide.md (VMs still valid for quick start) - Fixed broken link to use existing ../lte/deploy_install_docker.md Part of Issue #45 --- readmes/basics/introduction.md | 2 +- readmes/basics/quick_start_guide.md | 10 +++------- readmes/bazel/agw_with_bazel.md | 7 ------- readmes/feg/s1ap_federated_tests.md | 2 -- readmes/lte/dev_unit_testing.md | 2 -- readmes/orc8r/dev_gateway_registration.md | 2 -- 6 files changed, 4 insertions(+), 21 deletions(-) diff --git a/readmes/basics/introduction.md b/readmes/basics/introduction.md index bb27464..76cf27c 100644 --- a/readmes/basics/introduction.md +++ b/readmes/basics/introduction.md @@ -68,7 +68,7 @@ Magma leverages a variety of modern technologies to implement its solutions: Magma supports multiple deployment methods for the Access Gateway (AGW): -- **Docker-based AGW** (Recommended): The modern, containerized approach for development and production. See the [AGW Docker deployment guide](../deployment/agw/docker.md). +- **Docker-based AGW** (Recommended): The modern, containerized approach for development and production. See the [AGW Docker deployment guide](../lte/deploy_install_docker.md). - **Bare Metal**: For production deployments on physical hardware. > **Deprecation Notice**: Vagrant-based AGW deployment has been **deprecated** and will be removed in a future release. Please migrate to the Docker-based deployment method. See the Vagrant-to-Docker migration guide in issue [#15754](https://github.com/magma/magma/issues/15754) for detailed instructions. diff --git a/readmes/basics/quick_start_guide.md b/readmes/basics/quick_start_guide.md index cc903ba..725fa6d 100644 --- a/readmes/basics/quick_start_guide.md +++ b/readmes/basics/quick_start_guide.md @@ -11,21 +11,17 @@ installing Magma for a production deployment. With the [prereqs](prerequisites.md) installed, we can now set up a minimal end-to-end system on your development environment. In this guide, we'll start -by running the LTE access gateway (via Docker) and orchestrator cloud, and then +by running the LTE access gateway and orchestrator cloud, and then register your local access gateway with your local cloud for management. -> **Note**: Vagrant-based development has been deprecated. Please use the -> Docker-based AGW deployment. See the [AGW Docker deployment guide](../deployment/agw/docker.md) -> for the latest instructions. - ## Provisioning the environment Go ahead and open up 2 fresh terminal tabs. -### Terminal Tab 1: Provision the AGW (Docker) +### Terminal Tab 1: Provision the AGW VM The development environment can use Docker to run the Access Gateway. See the -[AGW Docker deployment](../deployment/agw/docker.md) for detailed instructions. +[AGW Docker deployment](../lte/deploy_install_docker.md) for detailed instructions. For quick setup: diff --git a/readmes/bazel/agw_with_bazel.md b/readmes/bazel/agw_with_bazel.md index fc6c9e6..e996953 100644 --- a/readmes/bazel/agw_with_bazel.md +++ b/readmes/bazel/agw_with_bazel.md @@ -110,13 +110,6 @@ The following Magma environments currently support Bazel: - The devcontainer is defined in `.devcontainer/Dockerfile` and meant for local development. The docker image is published at [`ghcr.io/magma/magma/devcontainer:latest`](https://github.com/magma/magma/pkgs/container/magma%2Fdevcontainer). - **Bazel-base** - The Bazel-base docker container is a minimal container where only required dependencies are installed. While this image is mainly intended to be used in CI, it can also be useful for local testing. The Bazel-base image is defined in `.devcontainer/bazel-base/Dockerfile` and published at [`ghcr.io/magma/magma/bazel-base:latest`](https://github.com/magma/magma/pkgs/container/magma%2Fbazel-base). - - Vagrant VMs (Deprecated) - - **magma-dev** - - The magma-dev virtual machine is intended for local development and for extended testing in CI. It can be used to run the Magma AGW services, as well as e.g. the [Python sudo tests](#python-sudo-tests). - - > **Note**: Vagrant-based development has been deprecated. Use Docker-based AGW instead. - - **magma-test** - - The magma-test virtual machine is used in CI to run the [LTE integration tests](#lte-integration-tests). - - > **Note**: Vagrant-based testing has been deprecated. ### Caching diff --git a/readmes/feg/s1ap_federated_tests.md b/readmes/feg/s1ap_federated_tests.md index da8ea32..880a25a 100644 --- a/readmes/feg/s1ap_federated_tests.md +++ b/readmes/feg/s1ap_federated_tests.md @@ -6,8 +6,6 @@ hide_title: true # S1AP Federated Integration Tests -> **Note**: Vagrant-based testing has been deprecated. Docker-based deployment is now recommended. - The S1AP Integration Test only tests the AGW. The objective of the **S1AP Federated Integration Tests** is to provide a test platform to run Magma with all of its components. That is, end-to-end tests with all diff --git a/readmes/lte/dev_unit_testing.md b/readmes/lte/dev_unit_testing.md index eac5a60..2d4a5ba 100644 --- a/readmes/lte/dev_unit_testing.md +++ b/readmes/lte/dev_unit_testing.md @@ -12,8 +12,6 @@ This guide covers tips for quickly validating AGW changes. Unit testing for AGW can be done either inside the Docker-based AGW container, the devcontainer, or bazel-base Docker containers. -> **Note**: Vagrant-based testing has been deprecated. Please use Docker containers. - To use Docker-based AGW, run: ```bash diff --git a/readmes/orc8r/dev_gateway_registration.md b/readmes/orc8r/dev_gateway_registration.md index cf06589..867a91d 100644 --- a/readmes/orc8r/dev_gateway_registration.md +++ b/readmes/orc8r/dev_gateway_registration.md @@ -41,8 +41,6 @@ The control proxy must have `\n` characters as line breaks. Here is a sample req The registration token expires every 30 minutes and automatically refreshes every time the operator fetches this unregistered gateway. 2. The operator runs the `register.py` script at the gateway with the registration token and its Orc8r's domain name. - > **Note**: Vagrant-based AGW has been deprecated. Please use Docker-based AGW deployment. - ```shell MAGMA-CONTROL$ docker exec -it magma_control /bin/bash MAGMA-CONTROL$ sudo /opt/magma/bin/python3 /opt/magma/orc8r/gateway/python/scripts/register.py [-h] [--ca-file CA_FILE] [--cloud-port CLOUD_PORT] [--no-control-proxy] DOMAIN_NAME REGISTRATION_TOKEN