Rewrite of Docker docs

packages/documentation/copy/en/reference/Containerized Execution.md

@@ -27,10 +27,13 @@ This specifies that the base image is the latest version of `alpine`, a very sma
 How to use this depends on whether your application is federated. You will need to [install Docker](https://docs.docker.com/get-docker/) if you haven't already in order to use this.
 
 ## Unfederated Execution
+Suppose your LF source file is `src/Foo.lf`. When you run `lfc` or use the IDE to generate code, a file called `Dockerfile` and a file called `docker-compose.yml` will appear in the `src_gen/Foo` directory, see [Structure of an LF project](/docs/handbook/a-first-reactor#structure-of-an-lf-project) for more info.
 
-### Using docker build and docker run
+### Using docker compose up
+After running `lfc`, change to the directory that contains the generated sources. Then, use `docker compose up --build` to automatically build the Docker image and run the container. Once the container finishes execution, use `docker compose down` in the same directory where `docker-compose.yml` is located to remove the container.
 
-Suppose your LF source file is `src/Foo.lf`. When you run `lfc` or use the IDE to generate code, a file called `Dockerfile` will appear in the `src_gen/Foo` directory, see [Structure of an LF project](/docs/handbook/a-first-reactor#structure-of-an-lf-project) for more info. You can build a Docker image as follows. First, navigate into the directory where `Dockerfile` is located. Then issue the command:
+### Using docker build and docker run
+You can also build the image and run the container in separate steps. Again, make sure that you have changed directory to the location of the `Dockerfile`. Then issue the command:
 
 ```sh
    docker build -t foo .
@@ -41,7 +44,7 @@ This will create a Docker image with tag `foo`. The tag is required to be all lo
 You can then use this tag to run the image in a container:
 
 ```sh
-    docker run -t --rm foo
+   docker run -t --rm foo
 ```
 
 The `-t` option creates a pseudo terminal, which is necessary for you to see any output produced by your program to `stdout`. If your program also reads from `stdin`, then you will need to give the `-i` option as well, or combine the two as `it`.
@@ -56,64 +59,51 @@ The above run command can include any supported command-line arguments to the LF
     docker run -t --rm foo --timeout 20 sec
 ```
 
-### Using docker compose up
-
-When you use `lfc` to compile `Foo.lf`, a file called `docker-compose.yml` will also appear in the same directory where `Foo.Dockerfile` is located. `cd` to that directory. Then, use `docker compose up` to automatically build and run the container. Once the container finishes execution, use `docker compose down` in the same directory where `docker-compose.yml` is located to remove the container.
-
 ## Federated Execution
+Suppose your LF source file is `src/Fed.lf`. When you run `lfc` or use the IDE to generate code, a file called `Dockerfile` is created for each federate alongside its sources. Just like in the unfederated case, a single `docker-compose.yml` will appear in the `src_gen/Fed` directory, see [Structure of an LF project](/docs/handbook/a-first-reactor#structure-of-an-lf-project) for more info.
 
-### Using docker build and docker run
-
-For a federated Lingua Franca program, one Dockerfile is created for each federate plus an additional one for the RTI. The Dockerfile for the RTI will be generated at `src-gen/RTI`. You will need to run `docker build` for each of these. For example, to build the image for the RTI, you can do this:
-
+### Using docker compose up
+Change directory to where the `docker-compose.yml` is located, and simply run:
 ```sh
-docker build -t distributedcountcontainerized_rti -f src-gen/DistributedCountContainerized_RTI.Dockerfile .
+    docker compose up --build 
 ```
+This will build images for all the federates (and the RTI, which is pulled from [Docker Hub](https://hub.docker.com/r/lflang/rti)), and run them on jointly on a shared network.
 
-This is for the [DistributedCountContainerized.lf](https://github.com/lf-lang/lingua-franca/blob/master/test/C/src/docker/federated/DistributedCountContainerized.lf), a federated that automatically runs in multiple Docker containers (one for the RTI and one for each federate) in continuous integration.
+### Using docker build and docker run
+You can also build the images and run the containers in separate steps, for each container individually. 
 
-Now, there are several options for how to proceed. One is to create a named network on which to run your federation. For example, to create a network named `lf`, do this:
+To build a particular federate that we assume is called `foo`, change directory to `src-gen/Fed/federate__foo` (there should be a `Dockerfile` in this directory). Then issue the command:
 
 ```sh
-    docker network create lf
+   docker build -t foo .
 ```
 
-You can then run the RTI on this network and assign the RTI a name that the federates can use to find the RTI:
+Assuming there is one more federate in the program that is called `bar`, change directory to `src-gen/Fed/federate__bar` and run:
 
 ```sh
-    docker run -t --rm --network lf --name distributedcount-rti distributedcount_rti
+   docker build -t bar .
 ```
 
-Here, the assigned name is not quite the same as the tag that was specified when building the image (the last argument is the tag of the image to run in a container) because a host name is not allowed to have an underscore in it.
-
-Currently, you will also have to specify this host name in the LF source file so that the federates know where to find the RTI. E.g., in [DistributedCount.lf](https://github.com/lf-lang/lingua-franca/blob/master/test/C/src/federated/DistributedCount.lf), change the end of the file to read as follows:
-
-```lf
-federated reactor DistributedCount at distributedcount-rti {
-    c = new Count();
-    p = new Print();
-    c.out -> p.in after 200 msec;
-}
+To pull the RTI from DockerHub, run this command:
+```sh
+   docker pull lflang/rti:rti
 ```
-
-Notice the `at distributedcount-rti`, which must match the name you use when running the RTI. **FIXME:** We should find a way to make this more automatic!
-
-In two other terminals, you can now run the other federates on the same network:
+Now, create a named network on which to run your federation. For example, to create a network named `lf`, do this:
 
 ```sh
-docker run -t --rm --network lf distributedcount_c
+    docker network create lf
 ```
 
-and
+You can then launch the RTI on this network (do this in a separate terminal):
 
 ```sh
-docker run -t --rm --network lf distributedcount_p
+     docker run -t --rm --name rti --network lf lflang/rti:rti -n 2 -i 1234
 ```
 
-### Using docker compose up
-
-For a federated Lingua Franca program, once you use `lfc` to compile `Foo.lf`, on top of the `docker-compose.yml` for the reactors, an additional `docker-compose.yml` will be generated for the RTI and placed in `src-gen/RTI`.
+Here, the `-n 2` indicates that the total number of federates is two and `-i 1234` assigns an identifier for the federation.
 
-To run the federated program, open two terminals. In the first terminal, go to `src-gen/RTI` and use `docker compose up` to build and run the containerized RTI. Wait until the RTI is booted up. Then, open a second terminal and `cd` to the top level folder of the program (this is the folder that contains one folder for each of the federated reactors). You should see a `docker-compose.yml` there. Run `docker compose up` to build and run the containers.
-
-Once the program finished executing, run `docker compose down` in both the folder that contains the `docker-compose.yml` for the RTI as well as the folder that contains the `docker-compose.yml` for the reactors to remove the containers.
+The federates `foo` and `bar`, the images of which have already been built, can be started using the following commands:
+```sh
+docker run -t --rm --network lf foo
+docker run -t --rm --network lf bar
+```