Run a sample application

The core Gramine repository contains sample applications to test the Gramine installation. To clone the Gramine repo, use the following command:

git clone --depth 1  https://github.com/gramineproject/gramine.git

Don’t build Gramine if it is already installed on the system.

Prerequisite

Please refer to Set up the host environment section to set up the host environment.

Build and run HelloWorld sample app

To build the HelloWorld application, install the gcc compiler and the make build system by entering one of the following:

# for Ubuntu distribution
sudo apt-get install gcc make

# for RHEL-like distribution
sudo dnf install gcc make

# for Alpine distribution
sudo apk add build-base make

Go to the HelloWorld example directory:

cd gramine/CI-Examples/helloworld

Build and run without SGX:

make
gramine-direct helloworld

Build and run with SGX:

make SGX=1
gramine-sgx helloworld

If you want to run this example on Alpine, then before building, modify the helloworld.manifest.template file: replace gramine.runtimedir() with gramine.runtimedir('musl'). For details, see the section “glibc vs musl” below.

Troubleshooting

  • “Signing key does not exist” error

If the following error occurs, please refer to Prepare a signing key section to prepare a key if you haven’t done so:

$ make SGX=1
Error: Invalid value for "--key" / "-k": File "~/.config/gramine/enclave-key.pem" does not exist.
make: *** [Makefile:44: sgx_sign] Error 2

  • “Cannot open SGX driver device” error

If the following error occurs, please refer to Set up the host environment section to check the system environment for SGX compatibility:

$ gramine-sgx helloworld
error: Cannot open SGX driver device.  [...]

Other sample applications

Several applications that demonstrate Gramine usability are available in the CI-Examples directory in the repository. Each application contains a short README file with instructions how to test it. We recommend starting with a thoroughly documented example of Redis to understand manifest options and Gramine features.

Additional sample Gramine configurations for applications are available in a separate repository: https://github.com/gramineproject/examples.

Please note that these sample applications are tested on Debian/Ubuntu. Most of these applications are also known to run correctly on Alpine and RHEL-like distributions (Fedora, CentOS Stream, AlmaLinux, Rocky Linux) but with caveats:

  • On RHEL-like distributions, Makefiles should be invoked with ARCH_LIBDIR=/lib64 make.

  • On Alpine, manifest files must use gramine.runtimedir('musl') instead of gramine.runtimedir(), and Makefiles should be invoked with ARCH_LIBDIR=/lib make.

  • Applications that rely on specific versions/builds of Glibc may break (our GCC example is known to work only on Ubuntu).

glibc vs musl

Most of the examples we provide use GNU C Library (glibc). If your application is built against musl libc, you can pass 'musl' to gramine.runtimedir() when generating the manifest from a template, which will mount musl libc (instead of the default glibc).