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 ofgramine.runtimedir()
, and Makefiles should be invoked withARCH_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).