Apache OpenServerless (incubating)

Welcome to Apache OpenServerless, an incubating project at the Apache Software Foundation.

• If you want to install Apache OpenServerless to use it go here. If you are in a hurry go straight to the quick start.
• If you want to contribute to the project, read this the contribution guide and the developer guide.
• If you want to discuss with us, join our mailing list by sending an email to dev-subscribe@openserverless.apache.org

[!IMPORTANT] The rest of this document covers building Apache OpenServerless from source, for developers of the project itself.

[!WARNING] Building from the latest sources in git is not recommended for production use. The main branch may contain unstable, untested, or incomplete changes. For production deployments, use an official release tarball instead.

Build and test from sources

Download a release tarball from the Apache distribution area, untar and cd to it:

curl -O https://dist.apache.org/repos/dist/dev/incubator/openserverless/<version>/openserverless-<version>-incubating-src.tar.gz
tar xzvf openserverless-<version>-incubating-src.tar.gz
cd openserverless-<version>-incubating-src

where <version> is the release you want, for example v0.9.0. Browse the distribution area to see the available versions.

Release artifacts are signed. Before building, verify the tarball against the project KEYS file:

curl -O https://dist.apache.org/repos/dist/dev/incubator/openserverless/<version>/openserverless-<version>-incubating-src.tar.gz.asc
curl -O https://dist.apache.org/repos/dist/dev/incubator/openserverless/KEYS
gpg --import KEYS
gpg --verify openserverless-<version>-incubating-src.tar.gz.asc

or clone the latest sources from the main branch or a release branch:

git clone --branch <branch> https://github.com/apache/openserverless --recurse-submodules
cd openserverless

[!IMPORTANT] Most of the code lives in git submodules, so --recurse-submodules is required. If you already cloned without it, run git submodule update --init --recursive before building, otherwise the submodule directories are empty and the build fails in confusing ways.

You can then build and test as follows.

Linux

You need Ubuntu 22+ or Debian 11+. Execute:

./build-and-test-ubuntu.sh

It can work on other distros but you have to adapt the scripts.

Windows

You need Windows 10/11 with WSL. Execute from PowerShell:

.\build-and-test-windows.ps1

macOS

You have to install lima (example: brew install lima). Execute:

./build-and-test-mac.sh

Each script builds and tests inside a disposable Linux VM or WSL distribution, so the build never touches your host toolchain.

Development setup

Prerequisites

• you need a Unix environment, either macOS, Linux or Windows WSL.
• you need docker on the path
• you need go available on the path
• you need task (https://taskfile.dev) available in the path
• you need jq, zip, unzip and kubectl available on the path
• you need license-eye on the path, to check the license headers

The per-platform sections below install all of these. Here are the procedures for macOS, Windows 11 and Ubuntu Linux.

Prepare Mac

On Mac, install brew and Docker Desktop, then do

brew install task go jq kubernetes-cli
go install github.com/apache/skywalking-eyes/cmd/license-eye@latest
export PATH="$PATH:$(go env GOPATH)/bin"

Prepare Windows

On Windows,

• install Docker Desktop, then
• wsl --install Ubuntu-24.04

then enable docker to be used in the distro Ubuntu-24.04

Access the distro (wsl -d Ubuntu-24.04), configure a new user, then execute:

sudo apt-get update
sudo apt-get -y install jq unzip zip
sudo snap install go --classic
sudo snap install task --classic
sudo snap install kubectl --classic
go install github.com/apache/skywalking-eyes/cmd/license-eye@latest
export PATH="$PATH:$(go env GOPATH)/bin"

Prepare Ubuntu or Debian Linux

Setup for a plain Ubuntu Linux with a user with sudo power:

sudo apt-get update
sudo apt-get -y install jq
sudo snap install go --classic
sudo snap install task --classic
sudo snap install kubectl --classic
curl -sL get.docker.com | sudo bash
go install github.com/apache/skywalking-eyes/cmd/license-eye@latest
export PATH="$PATH:$(go env GOPATH)/bin"
sudo usermod -aG docker $USER
newgrp docker
docker ps

Procedure

git clone https://github.com/apache/openserverless --recurse-submodules
cd openserverless

To work on a release branch instead of main, add --branch <branch>. Remember that most of the code lives in git submodules, so --recurse-submodules is required; if you already cloned without it, run git submodule update --init --recursive.

You can build with: task build

You can run the test suite with: task test

You can check all the files have the license header: task license

Read the task files (that are basically shell scripts wrapped in a yaml environment) to learn all the build procedures.

For a guided tour of how the system is put together — the cli, the opsroot.json configuration, how tags drive the builds, the development loop and how images are published — read the developer guide.

License

Apache OpenServerless is licensed under the Apache License, Version 2.0. See also the NOTICE file.

Disclaimer

Apache OpenServerless (Incubating) is an effort undergoing incubation at the Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC.

Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.

While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.