diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 960f220227..25f9cc97f6 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -101,6 +101,17 @@ Note on branches: * The 2.1, 2.2, 2.3, 2.4, 2.5, etc. branches are the branches for each major release and there are tags based on these with a third digit for minor patches +Install NVFlare from source +---------------------------- + +Navigate to the NVFlare repository and use pip install with development mode (can be useful to access latest nightly features or test custom builds for example): + +.. code-block:: shell + + $ git clone https://github.com/NVIDIA/NVFlare.git + $ cd NVFlare + $ pip install -e . + .. _containerized_deployment: @@ -197,11 +208,31 @@ Production mode is secure with TLS certificates - depending the choice the deplo Using non-HA, secure, local mode (all clients and server running on the same host), production mode is very similar to POC mode except it is secure. -Which mode should I choose for running NVFLARE? +Which mode should I choose for running NVFLARE? (Note: the same jobs can be run in any of the modes, and the same project.yml deployment options can be run in both POC mode and production.) + +.. list-table:: NVIDIA FLARE Modes + :header-rows: 1 + + * - **Mode** + - **Documentation** + - **Description** + * - Simulator + - :ref:`fl_simulator` + - | The FL Simulator is a light weight simulation where the job run is automated on a + | single system. Useful for quickly running a job or experimenting with research + | or FL algorithms. + * - POC + - :ref:`poc_command` + - | POC mode establishes and connects distinct server and client "systems" which can + | then be orchestrated using the FLARE Console all from a single machine. Users can + | also experiment with various deployment options (project.yml), which can be used + | in production modes. + * - Production + - :ref:`provisioned_setup` + - | Real world production mode involves a distributed deployment with generated startup + | kits from the provisioning process. Provides provisioning tool, dashboard, and + | various deployment options. - - For a quick research run, use the FL Simulator - - For simulating real cases within the same machine, use POC or production (local, non-HA, secure) mode. POC has convenient ``nvflare poc`` commands for ease of use. - - For all other cases, use production mode. .. _starting_fl_simulator: @@ -376,4 +407,18 @@ To start the server and client systems without an admin console: nvflare poc start -ex admin@nvidia.com +We can use the :ref:`job_cli` to easily submit a job to the POC system. (Note: We can run the same jobs we ran with the simulator in POC mode. If using the :ref:`fed_job_api`, simply export the job configuration with ``job.export_job()``.) + +.. code-block:: + + nvflare job submit -j NVFlare/examples/hello-world/hello-numpy-sag/jobs/hello-numpy-sag + +.. code-block:: + + nvflare poc stop + +.. code-block:: + + nvflare poc clean + For more details, see :ref:`poc_command`. diff --git a/docs/user_guide/nvflare_cli/poc_command.rst b/docs/user_guide/nvflare_cli/poc_command.rst index 70927bc93a..9f5d45e021 100644 --- a/docs/user_guide/nvflare_cli/poc_command.rst +++ b/docs/user_guide/nvflare_cli/poc_command.rst @@ -7,6 +7,8 @@ Proof Of Concept (POC) Command The POC command allows users to try out the features of NVFlare in a proof of concept deployment on a single machine. +Different processes represent the server, clients, and the admin console, making it a useful tool in preparation for a distributed deployment. + Syntax and Usage ================= @@ -292,7 +294,7 @@ will start ALL clients (site-1, site-2) and server as well as FLARE Console (aka .. note:: - If you prefer to have the FLARE Console on a different terminal, you can start everything else with: ``nvflare poc start -ex admin``. + If you prefer to have the FLARE Console on a different terminal, you can start everything else with: ``nvflare poc start -ex admin@nvidia.com``. Start the server only ---------------------- @@ -356,6 +358,59 @@ If there is no GPU, then there will be no assignments. If there are GPUs, they w nvidia-smi --list-gpus +Operating the System and Submitting a Job +========================================== +After preparing the poc workspace and starting the server, clients, and console (optional), we have several options to operate the whole system. + +First, link the desired job directory to the admin's transfer directory: + +.. code-block:: none + + nvflare poc prepare-jobs-dir -j NVFlare/examples + +FLARE Console +-------------- +After starting the FLARE console with: + +.. code-block:: none + + nvflare poc start -p admin@nvidia.com + +Login and submit the job: + +.. code-block:: none + + submit_job hello-world/hello-numpy-sag/jobs/hello-numpy-sag + +Refer to :ref:`operating_nvflare` for more details. + +FLARE API +--------- +To programmatically operate the system and submit a job, use the :ref:`flare_api`: + +.. code-block:: python + + import os + from nvflare.fuel.flare_api.flare_api import new_secure_session + + poc_workspace = "/tmp/nvflare/poc" + poc_prepared = os.path.join(poc_workspace, "example_project/prod_00") + admin_dir = os.path.join(poc_prepared, "admin@nvidia.com") + sess = new_secure_session("admin@nvidia.com", startup_kit_location=admin_dir) + job_id = sess.submit_job("hello-world/hello-numpy-sag/jobs/hello-numpy-sag") + + print(f"Job is running with ID {job_id}") + + +Job CLI +------- +The :ref:`job_cli` also provides a convenient command to submit a job: + +.. code-block:: none + + nvflare job submit -j NVFlare/examples/hello-world/hello-numpy-sag/jobs/hello-numpy-sag + + Stop Package(s) =============== @@ -381,3 +436,9 @@ There is a command to clean up the POC workspace added in version 2.2 that will .. code-block:: nvflare poc clean + +Learn More +=========== + +To learn more about the different options of the POC command in more detail, see the +:github_nvflare_link:`Setup NVFLARE in POC Mode Tutorial `. diff --git a/examples/tutorials/setup_poc.ipynb b/examples/tutorials/setup_poc.ipynb index d07c579882..0a64706a5d 100644 --- a/examples/tutorials/setup_poc.ipynb +++ b/examples/tutorials/setup_poc.ipynb @@ -7,11 +7,10 @@ "source": [ "# Set Up NVFLARE in POC Mode\n", "\n", - "[POC mode](https://nvflare.readthedocs.io/en/main/user_guide/nvflare_cli/poc_command.html) allows users to test the features of a full FLARE deployment on a single machine, without the overhead of a true distributed deployment.\n", + "This tutorial covers in depth the available features of the POC mode. For more basic setup guides, refer to the [Quickstart](https://nvflare.readthedocs.io/en/main/quickstart.html#setting-up-the-application-environment-in-poc-mode) or [POC Mode Documentation](https://nvflare.readthedocs.io/en/main/user_guide/nvflare_cli/poc_command.html).\n", "\n", - "Compared to the FL Simulator, where the job run is automated on a single system, POC mode allows you to establish and connect distinct server and client \"systems\" which can then be orchestrated using the FLARE Console. This can be useful in preparation for a distributed deployment.\n", - "\n", - "You can also experiment your deployment options (project.yml) using POC mode. \n", + "POC mode allows users to test the features of a full FLARE deployment on a single machine, without the overhead of a true distributed deployment.\n", + "Compared to the FL Simulator, where the job run is automated on a single system, POC mode allows you to establish and connect distinct server and client \"systems\" which can then be orchestrated using the FLARE Console. Users can also experiment with various deployment options (project.yml), making POC mode a useful tool in preparation for a distributed deployment.\n", "\n", ">It is ideal to start your NVFLARE system in POC mode from a **terminal**, not from a notebook. The terminal's virual env. must match the kernel's virtual env. In our case, we are using 'nvflare_example'.\n", "\n", @@ -27,8 +26,7 @@ }, "outputs": [], "source": [ - "\n", - "! nvflare poc -h\n" + "! nvflare poc -h" ] }, { @@ -38,7 +36,7 @@ "source": [ "We can further look at the help description for each command\n", "\n", - "> We will need ```tree``` command, so we will install ```tree``` in linux, if tree is not avaialble to you, you can replace it with 'ls -al`" + "> We will need ```tree``` command, so we will install ```tree``` in linux, if tree is not available to you, you can replace it with 'ls -al`" ] }, { @@ -58,36 +56,35 @@ "id": "7f877f82", "metadata": {}, "source": [ - "#### **POC Workspace**" + "## Configure the POC Workspace" ] }, { "cell_type": "markdown", - "id": "39e5192f-5f6d-4695-bc06-a04928b5f214", - "metadata": { - "tags": [] - }, + "id": "d0eb71b3-331e-4caa-996b-bf9af5490c62", + "metadata": {}, + "source": [ + "### Config command\n", + "\n", + "The config command can be used to configure the `poc_workspace`, as well as other locations such as the `startup_kit` and `job_template` directories." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "16f06739", + "metadata": {}, + "outputs": [], "source": [ - "if you want to change default POC workspace, you can do the followings" + "! nvflare config -h" ] }, { "cell_type": "markdown", - "id": "d0eb71b3-331e-4caa-996b-bf9af5490c62", + "id": "6bc86c64", "metadata": {}, "source": [ - "* Config command\n", - "\n", - "If you prefer not to use environment variable, you can do the followings: \n", - "\n", - "```\n", - "! nvflare config -pw /tmp/nvflare/poc --job_templates_dir ../../job_templates\n", - "\n", - "```\n", - "or \n", - "```\n", - "! nvflare config --poc_workspace_dir /tmp/nvflare/poc --job_templates_dir ../../job_templates\n", - "```" + "To specify the POC workspace, use the `--poc_workspace_dir` or `-pw` option:" ] }, { @@ -104,283 +101,278 @@ }, { "cell_type": "markdown", - "id": "fdfa4ec8-7fa6-4360-85d1-4b9f0448ca1a", - "metadata": {}, + "id": "17f368e9-6c66-4076-b12f-25330d4420c2", + "metadata": { + "tags": [] + }, "source": [ - "Look at the nvflare config command" + "### Hidden Config\n", + "\n", + "The config command works by writing the POC workspace directory to a hidden configuration file, which can also be edited directly:" ] }, { "cell_type": "code", "execution_count": null, - "id": "23dc2b30-f334-4d28-9102-194cfd55eebc", + "id": "a98e4fbe-43ce-4e30-8017-46d21fe81b31", "metadata": { "tags": [] }, "outputs": [], "source": [ - "! nvflare config -h" + "! cat ~/.nvflare/config.conf" ] }, { "cell_type": "markdown", - "id": "53f523f9-0413-4949-93f4-34fb0112d89d", + "id": "524a9d03-cbca-467f-8cf3-46f9481f1dca", "metadata": {}, "source": [ - "This should set the default variable to the following config file: ```~/.nvflare/config.conf```\n" + "### Environment Variable\n", + "\n", + "You can also use the env. variable NVFLARE_POC_WORKSPACE if you prefer. If both the hidden config file and env. variable NVFLARE_POC_WORKSPACE are set, the env. variable will take the precedence." ] }, { - "cell_type": "markdown", - "id": "735beb3b-f4ac-498f-af14-7ab9918371c9", + "cell_type": "code", + "execution_count": null, + "id": "b761c9e9", "metadata": {}, + "outputs": [], "source": [ - "One can set the POC_WORKSPACE_DIR as well as other locations such as startup_kit_dir and job_templates_dir as well. " + "%env NVFLARE_POC_WORKSPACE=/tmp/nvflare/poc\n", + "! echo $NVFLARE_POC_WORKSPACE " ] }, { "cell_type": "markdown", - "id": "17f368e9-6c66-4076-b12f-25330d4420c2", - "metadata": { - "tags": [] - }, + "id": "4b5f79f8-4146-4222-a991-a2411dc72b79", + "metadata": {}, "source": [ - "* Hidden Config\n", - "\n", - "What config command does is to write the POC workspace directory to a hidden configuration file. \n", + "## Prepare the POC workspace\n", "\n", - "```\n", - "~/.nvflare/config.conf\n", - "```\n", + "Now that we've configured our POC configuration, we can prepare the POC workspace. By default, the following command will generate POC packages for a server and two clients. If there is a pre-existing POC workspace, you will be prompted whether to overwrite and create a new one.\n", "\n", - "You can also edit directly the config file without using the config command. " + "Below we explore the various prepare options:" ] }, { "cell_type": "code", "execution_count": null, - "id": "a98e4fbe-43ce-4e30-8017-46d21fe81b31", + "id": "0507ce83-ff64-4684-a97c-728d495158ad", "metadata": { "tags": [] }, "outputs": [], "source": [ - "!cat ~/.nvflare/config.conf" + "! nvflare poc prepare -h" ] }, { "cell_type": "markdown", - "id": "524a9d03-cbca-467f-8cf3-46f9481f1dca", + "id": "86468ce7", "metadata": {}, "source": [ - "You can also env. variable, NVFLARE_POC_WORKSPACE, if you prefer. If both hidden config file and env. variable NVFLARE_POC_WORKSPACE are set, env. variable will take the precedence.\n", - "```\n", - "%env NVFLARE_POC_WORKSPACE=/tmp/nvflare/poc\n", - "!echo $NVFLARE_POC_WORKSPACE \n", + "### Number of Clients\n", + "\n", + "Specify a different number of clients with -n:\n", "\n", "```\n", - " \n" + "nvflare poc prepare -n [NUMBER_OF_CLIENTS]\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9e205cf7", + "metadata": {}, + "outputs": [], + "source": [ + "! echo 'y' | nvflare poc prepare -n 2" ] }, { "cell_type": "markdown", - "id": "4b5f79f8-4146-4222-a991-a2411dc72b79", + "id": "5d900be1", "metadata": {}, "source": [ - "### Preparing the POC workspace\n", + "### Named Clients\n", "\n", - "Now that we've configured our POC configuration, we can prepare the POC workspace. By default, the following command will generate POC packages for a server and two clients.\n", - "nvflare poc prepare\n", - "```\n", - " nvflare poc prepare \n", - "```\n", + "Specifiy the client site names ((instead of use default site-1,2 etc.) with -c:\n", "\n", - "You can specify a different number of clients with the -n option:\n", - "\n", - "```\n", - " nvflare poc prepare -n N\n", "```\n", - "\n", - "If you running the POC prepare command, there is a prompt for user to answer." + "nvflare poc prepare -c [CLIENTS ...]\n", + "```" ] }, { - "cell_type": "markdown", - "id": "648d9e46-dce8-4b3d-b1be-bac290673907", + "cell_type": "code", + "execution_count": null, + "id": "26f6ca9c", "metadata": {}, + "outputs": [], "source": [ - "#### Various Prepare Options" + "! echo 'y' | nvflare poc prepare -c hospital-1 hospital-2" ] }, { "cell_type": "code", "execution_count": null, - "id": "0507ce83-ff64-4684-a97c-728d495158ad", - "metadata": { - "tags": [] - }, + "id": "e091b13c", + "metadata": {}, "outputs": [], "source": [ - "! nvflare poc prepare -h" + "! tree /tmp/nvflare/poc/example_project/prod_00" ] }, { "cell_type": "markdown", - "id": "2c89112c-3b38-49cf-bbb5-101ba2e58641", + "id": "78ac8384", "metadata": {}, "source": [ - "We have many options to prepare the POC workspace. let's look at some of them\n", + "### Docker Image\n", "\n", - "* use client's site name (instead of use default site-1,2 etc.)\n", + "The -d option instructs the provision tool to create a docker.sh use the specified docker_image. The docker.sh will start in detached mode. \n", "\n", "```\n", - "! nvflare poc prepare -c hospital-1 hospital-2\n", + "nvflare poc prepare -d [DOCKER_IMAGE]\n", "```\n", - "This will create two clients named **hospital-1** and **hospital-2**\n", - "\n", - "* -d docker_image\n", - "\n", - "This instruct the provision tool to create a docker.sh use the specified docker_image. The docker.sh will start in detached mode. \n", - "\n", - "* -i project.yml \n", - "\n", - "This optional allows you experiment the your project.yml locally, try local before used in production. \n", - "\n", - "* All specified options will resulting an project.yml file located at \n", "\n", - "/project.yml \n", - "\n", - "for example, ```/tmp/nvflare/poc/project.yml```\n", - "\n", - "\n", - "Let's try out some of options\n", - "\n", - "* **Named Clients**\n", - "\n", - "instead of using default site-1, site-2 etc. user can specified the client names" + "This will create docker.sh for each client and server which will run `docker pull docker_image` from docker hub, then running the docker in detached mode. The docker_image must use nvflare. For example, we use the following docker image \"nvflare/nvflare\" which has nvflare preinstalled.\n", + "> Note: you should build your own image if you want to include your dependencies such as pytorch etc.\n" ] }, { "cell_type": "code", "execution_count": null, - "id": "95749ed0-7e9d-4994-abe2-341fd299f801", - "metadata": { - "tags": [] - }, + "id": "7810bcc3", + "metadata": {}, "outputs": [], "source": [ - "! echo 'y' | nvflare poc prepare -c hospital-1 hospital-2\n" + "! echo 'y'| nvflare poc prepare -d 'nvflare/nvflare'" ] }, { - "cell_type": "markdown", - "id": "e4e559b4-6fff-44a2-aeb1-6b96e63888f5", + "cell_type": "code", + "execution_count": null, + "id": "ff2755e1", "metadata": {}, + "outputs": [], "source": [ - "Now, let's look at the result, if you have ```tree``` command installed in linux (``` pip install tree```), you can use it. otherwise, use ```ls -al```. " + "! tree /tmp/nvflare/poc/example_project/prod_00" ] }, { - "cell_type": "code", - "execution_count": null, - "id": "7cc85def-f768-4c49-883f-8bcfd13461da", - "metadata": { - "tags": [] - }, - "outputs": [], + "cell_type": "markdown", + "id": "9d3a3c06", + "metadata": {}, "source": [ - "! tree /tmp/nvflare/poc/example_project/prod_00" + "Notice the new \"docker.sh\", now each client will using docker run with we specified \"nvflare/nvflare\" docker image" ] }, { "cell_type": "markdown", - "id": "89add7ef-346b-40c9-97be-aa49c624adbb", + "id": "b6b968e9", "metadata": {}, "source": [ - "Now two clients are named \"hospital-1\" and \"hospital-2\". \n", + "### Homomorphic Encryption (HE)\n", "\n", - "* **Setup NVFLARE in docker mode**\n", - "\n", - "Normally, when we using ```nvflare poc start```, the clients and server are started as process in the local host. \n", - "What if you would like to experiment runing client and server in dockers ? You can do it now, \n", + "The -he option enables homomorphic encryption.\n", "\n", "```\n", - "nvflare poc prepare -n 2 -d \n", - "\n", + "nvflare poc prepare -he\n", "```\n", "\n", - "This will create docker.sh for each client and server which will run docker pull docker_image from docker hub, then running the docker in detached mode. The docker_image must use nvflare docker must have flare pre-installed. For example, we use the following docker image \"nvflare/nvflare\"\n", - "> Note: you should build your own image if you want to include your dependencies such as pytorch etc.\n" + "To support HE, we need the provision process to generate TenSEAL homomorphic encryption context for the server and client and write them to the server and client participant folders (See [provision context](https://nvflare.readthedocs.io/en/main/programming_guide/provisioning_system.html#provision-context)). This is achieved by the HEBuilder, which is automatically added to the `project.yml` file using the `-he` in the POC command (See the `-i` option to manually customize the `project.yml` file).\n", + "\n", + "First we must install nvflare with TenSEAL:\n", + "\n", + "> note: TenSEAL is not available in Mac OS" ] }, { "cell_type": "code", "execution_count": null, - "id": "45f77369-a7c6-45d0-aff9-d0f5b23829b5", - "metadata": { - "tags": [] - }, + "id": "42d15f8f", + "metadata": {}, "outputs": [], "source": [ - "! echo 'y'| nvflare poc prepare -d 'nvflare/nvflare'" + "! pip install nvflare[HE]" + ] + }, + { + "cell_type": "markdown", + "id": "dd704405", + "metadata": {}, + "source": [ + "For an example, we can prepare a POC workspace with HE enabled with the following command:" ] }, { "cell_type": "code", "execution_count": null, - "id": "4f154b6c-f353-48bb-8bed-aa1b6bc7c72f", - "metadata": { - "tags": [] - }, + "id": "3f3f05ab", + "metadata": {}, "outputs": [], "source": [ - "! tree /tmp/nvflare/poc/example_project/prod_00" + "! echo 'y' | nvflare poc prepare -he" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "39f96290", + "metadata": {}, + "outputs": [], + "source": [ + "! cat /tmp/nvflare/poc/project.yml" ] }, { "cell_type": "markdown", - "id": "6b2caf8a-36b9-4e56-b7be-836aec7f1c33", + "id": "40e0088f", "metadata": {}, "source": [ - "Notice the new \"docker.sh\", now each client will using docker run with we specified \"nvflare/nvflare\" docker image" + "Notice: ```path: nvflare.lighter.impl.he.HEBuilder``` is added to the YAML file.\n", + "Also note the importance of the order of the builders, as the `HEBuilder` must be configured before the `SignatureBuilder` to ensure the tenseal context files are signed." ] }, { "cell_type": "markdown", - "id": "2715f4d2-dd02-4a57-bfc5-985e1589dd18", - "metadata": { - "tags": [] - }, + "id": "37a6edd6", + "metadata": {}, "source": [ - "* **simulate production deployment setup locally**\n", - "\n", - "Assuming we have a new custom project.yml, we like to test out the project.yml locally before we do the real provision. \n", - "\n", - "We can actually do it with POC !\n", - "\n", + "### Project Input: Simulate production deployment setup locally" + ] + }, + { + "cell_type": "markdown", + "id": "3a801671", + "metadata": {}, + "source": [ + "Assuming we have a new custom project.yml, we can test out the project.yml locally in POC mode before we do the real provisionining.\n", "\n", "```\n", - "nvflare poc prepare -i \n", + "nvflare poc prepare -i [PROJECT_INPUT]\n", "```\n", "\n", - "Let's try this out. we have prepared an custom_project.yml file: \n" + "Let's try this out. We have prepared an custom_project.yml file: " ] }, { "cell_type": "code", "execution_count": null, - "id": "23b38275-4d12-492d-8b3b-47217e12625a", - "metadata": { - "tags": [] - }, + "id": "ad640119", + "metadata": {}, "outputs": [], "source": [ - "!cat ./custom_project.yml" + "! cat ./custom_project.yml" ] }, { "cell_type": "markdown", - "id": "b34b6723-b352-4e2b-b86e-77b9f03d26e1", + "id": "04fdf2e5", "metadata": {}, "source": [ "Notice in this project file, we define three sites: \n", @@ -392,17 +384,14 @@ "We also define few users: \n", "* admin@nonprofit.org, from nonprofit.org, serves as project admin\n", "* admin@hospital.org.us, lead@hospital.org.us, member@hospital.org.us from us_hospital, serves as org admin, lead and member for us_hospital respectively\n", - "\n", - "* admin@hospital.org.eu, lead@hospital.org.eu, member@hospital.org.eu from eu_hospital, serves as org admin, lead and member for eu_hospital respectively\n" + "* admin@hospital.org.eu, lead@hospital.org.eu, member@hospital.org.eu from eu_hospital, serves as org admin, lead and member for eu_hospital respectively" ] }, { "cell_type": "code", "execution_count": null, - "id": "1531cba4-5d46-4cd4-9a06-e9c7e1598a9a", - "metadata": { - "tags": [] - }, + "id": "61c668b2", + "metadata": {}, "outputs": [], "source": [ "! echo 'y' | nvflare poc prepare -i ./custom_project.yml" @@ -411,10 +400,8 @@ { "cell_type": "code", "execution_count": null, - "id": "35e52946-d307-45f3-ac52-e7190d556104", - "metadata": { - "tags": [] - }, + "id": "a9d143ab", + "metadata": {}, "outputs": [], "source": [ "! tree /tmp/nvflare/poc/health_project/prod_00" @@ -422,10 +409,10 @@ }, { "cell_type": "markdown", - "id": "a71a7f61-31dd-442a-8f43-0b25af7e58b1", + "id": "c8917139", "metadata": {}, "source": [ - "See we actually provisioned all participants" + "See that we successfully provisioned all participants from our \"custom_project.yml\"." ] }, { @@ -433,33 +420,27 @@ "id": "4b82a4b5-5eed-47a2-a888-0d140a5531bc", "metadata": {}, "source": [ - "### Prepare job example directories\n", + "## Prepare job example directories\n", "\n", - "By default, the command\n", - "\n", - "```\n", - "nvflare poc prepare \n", - "\n", - "```\n", - "command will setup symbolic link to the /examples directory, assuming the you have use \"git clone\" to download the NVFLARE from github directory and you have defined the NVFLARE_HOME env. variable. \n", - " \n", - "What if you just want to use your own jobs or not setup the NVFLARE_HOME env. variables ? You can use the following command to setup the job directories\n", + "By default, the `nvflare poc prepare` command will setup a symbolic link to the NVFlare/examples directory, assuming that you have used `git clone` to download NVFlare from github and have defined the NVFLARE_HOME env. variable.\n", " \n", - "```\n", - "nvflare poc prepare-jobs-dir -j \n", - "\n", - "```\n", - "\n", - "For example: \n", + "Rather than setting the NVFLARE_HOME env. variables, instead link to your desired jobs with the following command to setup to the job directory:\n", " \n", "```\n", - "nvflare poc prepare-jobs-dir -j /path/to/examples\n", - "\n", + "nvflare poc prepare-jobs-dir -j [JOBS_DIR]\n", "```\n", "\n", - " \n", - " \n", - " \n" + "For example we can set the jobs directory to NVFlare/examples: " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "41053a0c", + "metadata": {}, + "outputs": [], + "source": [ + "! nvflare poc prepare-jobs-dir -j .." ] }, { @@ -467,7 +448,7 @@ "id": "0efc93e2-fcc8-4789-822f-69e8d2d32116", "metadata": {}, "source": [ - "### Start NVFlare system in POC mode\n", + "## Start NVFlare system in POC mode\n", "\n", "When starting the POC deployment, it's necessary to use a separate terminal since the `nvflare poc start` command will run in the foreground emitting output from the server and any connected clients.\n", "\n", @@ -475,7 +456,7 @@ "\n", "In many cases, we want to start the clients and server, but without the FLARE console for project admin, as we are going to interact with the system from a notebook or CLI. You first need to find out the user name for the project admin. By default, this is admin@nvidia.com\n", "\n", - "Create a terminal to execute the following command (in JupyterLab or host terminal), then\n", + "Create a terminal to execute the following command (in JupyterLab or host terminal):\n", "\n", "```\n", " nvflare poc start -ex admin@nvidia.com\n", @@ -483,33 +464,23 @@ ">**Note:**\n", " Using ```%%bash -bg``` to run the above command in a code cell may not always work\n", " \n", - "#### A more complex example\n", + "### A More Complex Example\n", " \n", "In this example, lets see how to start the individual user participants defined in custom_project.yml. Note the project admin is \"admin@nonprofit.org\" instead of \"admin@nvidia.com\"\n", "\n", - "Please use terminal to try these commands\n", + "Please use terminal to try these commands:\n", "\n", - "* We start start without project admin console\n", + "1. We start the system with two hospital clients and server, without the project admin console:\n", "\n", "```\n", " nvflare poc start -ex admin@nonprofit.org\n", "```\n", "\n", - "This will start two hospital clients and server. \n", - "\n", - "* Next we like to start US hospital's lead's FLARE console \n", + "2. Next we like to start US hospital's lead's FLARE console:\n", "\n", "```\n", - "\n", - "nvflare poc start -p lead@hospital.org.us\n", - "\n", - "```\n", - "\n", - "You are acting as US hospital's lead \n", - "\n", - "\n", - "\n", - "\n" + " nvflare poc start -p lead@hospital.org.us\n", + "```" ] }, { @@ -519,7 +490,9 @@ "tags": [] }, "source": [ - "Once the system is up, we are now ready to go back to the notebook to work on your project." + "Once the system is up, we are now ready to go back to the notebook to work on your project.\n", + "\n", + "For more details on how to operate the FLARE system and submit jobs, refer to the [POC Mode Documentation](https://nvflare.readthedocs.io/en/main/user_guide/nvflare_cli/poc_command.html#operating-the-system-and-submitting-a-job)." ] }, { @@ -527,35 +500,21 @@ "id": "275fbe95-faf3-468d-a96a-453310e90aee", "metadata": {}, "source": [ - "### Stop FLARE system in POC\n", + "## Stop NVFlare system in POC mode\n", "\n", - "Once you are done with the FLARE system, you can shut down the poc system.\n", - "From terminal, issue the following command stop poc in the terminal\n", + "Once you are done with the NVFlare system, you can shut down the poc system.\n", + "From terminal, issue the following command to shutdown all participants including server, clients, and admin consoles.\n", "```\n", - " nvflare poc stop\n", + " nvflare poc stop\n", "```\n", "\n", - "This will shutdown all participants including server, clients, admin consoles\n", - "\n", - "If you like to shutdown invididual participant. You can use the following command\n", + "If you like to shutdown an invididual participant, use the following -p option:\n", "\n", "```\n", - " nvflare poc stop -p \n", - "```\n", - "\n", - "here are some examples depending on your prepared poc\n", - "\n", - "\n", + " nvflare poc stop -p [SERVICE]\n", "```\n", - " nvflare poc stop -p server\n", "\n", - " nvflare poc stop -p site-1\n", - " \n", - " nvflare poc stop -p admin@nvidia.com\n", - " \n", - " nvflare poc stop -p lead@hospital.org.us\n", - "```\n", - "\n" + "Some examples of service participant names can be \"server\", \"site-1\", \"admin@nvidia.com\", or \"lead@hospital.org.us\" depending on your prepared POC. " ] }, { @@ -565,13 +524,13 @@ "tags": [] }, "source": [ - "### Project Yaml File\n", + "## Project Yaml File\n", "\n", - "Once we experimented with different options, we are ready to move on to the production beyond local host. \n", - "You don't need to manual edit the project.yml to do so. The resulting project.yml is auto-generated for you and located at \n", + "Once we experimented with different options, we are ready to move on to the production beyond local host.\n", + "The same project.yml file can be used for production, and is auto-generated for you and located at:\n", "\n", "```\n", - " /project.yml\n", + " /project.yml\n", "```\n", "\n", "For example,\n" @@ -618,89 +577,9 @@ "id": "f74a5c2d-d7ad-4995-9940-9b98e9f9a4bf", "metadata": {}, "source": [ - "Copy this file and you are ready to go !" - ] - }, - { - "cell_type": "markdown", - "id": "fb3b39f3-18da-408e-8cb5-f762db52e1e6", - "metadata": {}, - "source": [ - "### Support Homomorphic Encryption (HE)\n", + "Copy this file and you are ready to go !\n", "\n", - "To support HE, we need the provision process to generate Tenseal homomorphic encryption context for the server and client and write them to the server and client participant folders. See [provision context](https://nvflare.readthedocs.io/en/main/programming_guide/provisioning_system.html#provision-context). This is achieved by the Provision builder, specifically for HE, HEBuilder. Instead of manually adding HEBuilder to the `project.yml` file, one can use `-he` in the POC command.\n", - "\n", - "For example, if we use the above command with HE, we can write as\n", - "\n", - "\n", - "```\n", - "echo 'y' | nvflare poc prepare -c hospital_1 hospital_2 -d 'nvflare/nvflare' -he\n", - "\n", - "```\n", - "\n", - "\n", - "```\n", - " pip install nvflare[HE]\n", - " \n", - "```\n", - "\n", - "\n", - "> note: Tenseal is not avaiable in Mac OS\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "18ab73d0-e52e-45c0-8ccd-887f9eef994a", - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "! pip install nvflare[HE]" - ] - }, - { - "cell_type": "markdown", - "id": "9a161d61-4688-4bd9-90c3-6d60e8e65015", - "metadata": {}, - "source": [ - "Assuming you installed it successfully, then you can run the command" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "373e048b-3e7f-4605-8583-61f1facf5fda", - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "! echo 'y' | nvflare poc prepare -c hospital_1 hospital_2 -d 'nvflare/nvflare' -he" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "0be81258-e10c-40dd-81ff-5a881995ee92", - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "! cat /tmp/nvflare/poc/project.yml\n" - ] - }, - { - "cell_type": "markdown", - "id": "99e75eda-f6b9-45ac-a383-52a17b21982a", - "metadata": { - "tags": [] - }, - "source": [ - "Notice: ```path: nvflare.lighter.impl.he.HEBuilder``` is added to the YAML file.\n", - "Also note the importance of the order of the builders, as the `HEBuilder` must be configured before the `SignatureBuilder` to ensure the tenseal context files are signed." + "Learn more about how to take your project to the real world with the provisioning tool, dashboard, and various deployment options in our [documentation](https://nvflare.readthedocs.io/en/main/real_world_fl/overview.html)." ] }, { @@ -708,9 +587,9 @@ "id": "ea8f1878-7e9d-4e17-ba78-5812fc88b580", "metadata": {}, "source": [ - "### Clean up POC workspace\n", + "## Clean up POC workspace\n", "\n", - "If you want to clean up the POC workspace and delete the poc workspace directory containing all packages you may have prepared, you can use the following command:" + "Lastly, if you want to clean up the POC workspace and delete the POC workspace directory containing all of the packages you may have prepared, you can use the following command:" ] }, {