Update docker/README.md

README.markdown

@@ -2,7 +2,7 @@
 
 ![CI build status](https://github.com/veracruz-project/veracruz/actions/workflows/main.yml/badge.svg)
 
-<img src = "https://confidentialcomputing.io/wp-content/uploads/sites/85/2019/08/cc_consortium-color.svg" width=192>
+<img src = "https://confidentialcomputing.io/wp-content/uploads/sites/10/2022/07/cc_consortium-color.svg" width=192>
 
 ## About
 

docker/Makefile

@@ -105,7 +105,7 @@ localci-exec:
 	docker exec -i -t $(CONTAINER)-localci-$(USER)-$(VERSION) /bin/bash || true
 
 localci-base: ci/Dockerfile.local ci-base
-	$(DOCKER_BUILD_CMD) $(BUILD_ARGS) -t $(IMAGE)/localci/$(USER):$(VERSION) -f $< .
+	$(DOCKER_BUILD_CMD) $(BUILD_ARGS) -t $(IMAGE)/localci:$(VERSION) -f $< .
 
 .PHONY: all-ci
 all-ci: ci-image localci-base
@@ -126,7 +126,7 @@ linux-exec:
 
 .PHONY:
 linux-base: linux/Dockerfile base
-	$(DOCKER_BUILD_CMD) $(BUILD_ARGS) -t $(IMAGE)/linux/$(USER):$(VERSION) -f $< .
+	$(DOCKER_BUILD_CMD) $(BUILD_ARGS) -t $(IMAGE)/linux:$(VERSION) -f $< .
 
 #####################################################################
 # Nitro-related targets
@@ -168,4 +168,4 @@ endif
 		(git fetch ; git checkout $(AWS_NITRO_CLI_REVISION))
 	make -C aws-nitro-enclaves-cli HOST_MACHINE=$(ARCH) nitro-cli
 	$(DOCKER_BUILD_CMD) $(BUILD_ARGS) \
-		--build-arg NE_GID=$(NE_GID) -t $(IMAGE)/nitro/$(USER):$(VERSION) -f $< .
+		--build-arg NE_GID=$(NE_GID) -t $(IMAGE)/nitro:$(VERSION) -f $< .

docker/README.md

@@ -1,144 +1,85 @@
 # Building Veracruz
 
-<img src = "https://confidentialcomputing.io/wp-content/uploads/sites/85/2019/08/cc_consortium-color.svg" width=192>
+<img src = "https://confidentialcomputing.io/wp-content/uploads/sites/10/2022/07/cc_consortium-color.svg" width=192>
 
-This is the repository for the Docker container used for developing Veracruz.
-Veracruz is an open-source runtime for collaborative privacy-preserving compute.
-The main Veracruz repository can be found [here](https://github.com/veracruz-project/veracruz).
-
-Veracruz is an adopted project of the Confidential Compute Consortium (CCC).
-
-## Supported platforms
-
-- AWS Nitro Enclaves
-- Linux (no TEE technology used)
+This directory has the code for building the Docker containers used
+for developing Veracruz.
 
 ## Requirements
 
-- **Docker:** 
+- **Docker:**
 We use Docker to provide a consistent build environment.  Follow this guide to [install Docker](https://docs.docker.com/engine/install/) if necessary.
-- **Enable Docker squash experimental feature:** *The tests are done on a linux machine. [To enable docker experimental features on another OS.](https://docs.docker.com/engine/reference/commandline/checkpoint_create/)*
-We use the `squash` docker experimental feature to help reduce the Veracruz docker image size, to enable this feature:
-    - run: 
-        ```sh 
-        sudo service docker stop
-        ```
-    - copy the following in `/etc/docker/daemon.json `
-        ```sh
-        {
-            "experimental": true
-        }
-        ```
-    - run:
-        ```sh 
-        sudo service docker start
-        ```
 
 ## Local build setup
 
-Once all the necessary requirements are available, run the following commands:
-- Clone the Veracruz repository: This will pull the docker submodule
-
-    ```
-    git clone --recursive https://github.com/veracruz-project/veracruz.git 
-    export VERACRUZ_ROOT=$PWD/veracruz
-    ```
-- Once you have a local copy of the Veracruz source:
-
-    ```
-    cd veracruz/docker
-    ```
-
-The following instructions depend on the platform you're building for. (SGX, Arm TZ)
-
-Note that building the Docker image will take a long time (we appreciate any suggestions on how this can be sped up!)
-
-- ### Build Instructions for AWS Nitro Enclaves
-    ```
-    make nitro-base
-    ```
-
-- ### Build Instructions for Linux
-    ```
-    make linux-base
-    ```
-
-- ### Starting the veracruz container
-    For AWS Nitro Enclaves:
-    ```
-    make nitro-run
-    ```
-
-    Or, for Linux:
-    ```
-    make linux-run
-    ```
-
-There should be a Docker container running called "veracruz_<PLATFORM>_<USERNAME>". To verify that it's running, run: 
-    ```
-    docker ps
-    ```
-
-You can now start a shell in the newly created container:
-    For Nitro:
+Enter this directory in a local copy of the Veracruz source:
 ```
-    make nitro-exec
+cd veracruz/docker
 ```
 
-    For Linux:
-```
-    make linux-exec
-```
+## Build and run
 
-## Test Instructions for AWS Nitro Enclaves
+There are several different Docker containers that can be used,
+depending on the platform. If you are new to Veracruz you should
+probably try `localci` first.
 
-Once inside the container, set up your local environment.
+### `localci`
 
-Now, to build the binaries:
+To build the container:
 ```
-cd workspaces/
-make nitro
+make localci-build
 ```
 
-and to run the tests:
-
+To run the container:
 ```
-cd workspaces/nitro-host/
-make test-server
-make veracruz-test
+make localci-run
 ```
 
-## Test Instructions for Linux
+With `docker ps` you should now be able to see the container running.
 
-Once inside the container, build the binaries:
+To get a shell in the container running as the appropriate non-root user:
 ```
-cd workspaces/
-make linux
+make localci-exec
 ```
 
-and to run the tests:
-
+The Veracruz tree should be mounted in the container, so you can run,
+for example:
 ```
-cd workspaces/linux-host/
-make test-server
-make veracruz-test
+cd /work/veracruz/workspaces
+make linux && make linux-tests
+make nitro
 ```
 
-# Cleaning a build
+(On an ordinary Linux system you can build for `nitro`, but not run
+the tests.)
 
-The Veracruz Makefile exposes a build target, `clean`, which recursively
-invokes `cargo clean` for each major subcomponent of the project.  However,
-sometimes this is not enough to fix a broken build environment (note that this
-is common when using `xargo` to build e.g. the examples, or the rest of the
-SDK).  In that case, it is useful to also delete the contents of the
-`~/.xargo` directory, in addition to the standard clean build process described
-above.
+### `linux`
 
-# Generating the certificates
+This is the same as `localci`, above, except only for the Linux
+platform.
 
-Cryptographic certificates can be generated by using the following `openssl`
-invocation:
+### `nitro`
 
-```
-openssl req -new -x509 -key <key filename> -sha256 -nodes -days 3650 -out <certificate filename> -config cert.conf 
+This is the same as `localci`, above, except only for the AWS Nitro
+platform and you can also run the Nitro tests on appropriate hardware.
+See the [Nitro instructions](../NITRO_INSTRUCTIONS.markdown).
+
+### `ci`
+
+This is the same as `localci`, above, except that you will run as
+root. This container is used for CI in the cloud.
+
+### Docker images
+
+```mermaid
+flowchart TD
+    A[ubuntu:22.04] -->|base/Dockerfile| B(veracruz/base:$VERSION)
+    B --> |linux/Dockerfile| C(veracruz/linux:$VERSION)
+    C --> |Dockerfile| D(veracruz/linux/$USER:$VERSION)
+    B --> |nitro/Dockerfile| E(veracruz/nitro:$VERSION)
+    E --> |Dockerfile| F(veracruz/nitro/$USER:$VERSION)
+    E --> |ci/Dockerfile.base| G(veracruz/ci-base:$VERSION)
+    G --> |ci/Dockerfile.cache| H(veracruz/ci:$VERSION)
+    G --> |ci/Dockerfile.local| I(veracruz/localci:$VERSION)
+    I --> |Dockerfile| J(veracruz/localci/$USER:$VERSION)
 ```