{"id":14987795,"url":"https://github.com/apache/openserverless","last_synced_at":"2025-05-15T16:04:49.091Z","repository":{"id":247214471,"uuid":"823106872","full_name":"apache/openserverless","owner":"apache","description":"Apache OpenServerless (incubating)","archived":false,"fork":false,"pushed_at":"2025-01-18T12:13:51.000Z","size":1207,"stargazers_count":541,"open_issues_count":10,"forks_count":15,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-03-31T21:44:26.637Z","etag":null,"topics":["cloud","kubernetes","openserverless","serverless"],"latest_commit_sha":null,"homepage":"https://openserverless.apache.org","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-02T12:41:21.000Z","updated_at":"2025-03-27T21:52:14.000Z","dependencies_parsed_at":"2025-02-07T19:10:43.215Z","dependency_job_id":"742f66eb-330b-48d4-9e9b-a0d2adf5c254","html_url":"https://github.com/apache/openserverless","commit_stats":{"total_commits":41,"total_committers":11,"mean_commits":3.727272727272727,"dds":0.7073170731707317,"last_synced_commit":"62be629d3b8d3821d68150f5dc7631e553cdd98b"},"previous_names":["apache/openserverless"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fopenserverless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fopenserverless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fopenserverless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fopenserverless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/openserverless/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247714836,"owners_count":20983950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud","kubernetes","openserverless","serverless"],"created_at":"2024-09-24T14:15:27.673Z","updated_at":"2025-04-07T22:05:08.346Z","avatar_url":"https://github.com/apache.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apache OpenServerless (incubating)\n\nWelcome to   [Apache OpenServerless](https://openserverless.apache.org), an incubating project at the [Apache Software Foundation](https://www.apache.org) \n\n- If you want to **install** Apache OpenServerless go [here](https://openserverless.apache.org/docs/installation/).\n- If you want to **understand** what this project is check the [original proposal](https://cwiki.apache.org/confluence/display/INCUBATOR/OpenServerlessProposal). \n- If you want to **contribute** to the project, read on this README to setup a **development** environment.\n- If you want to **chat** with us, join  [our Discord server](https://bit.ly/openserverless-discord).\n\n## Development Environment Overview\n\nApache OpenServerless is a complex project with lots of dependencies. It also needs a Kubernetes cluster to be executed, tested and developed on.\n\nYou may setup the environment by yourself, but it can take a lot of time so we prepared a procedure to setup quickly a ready-to-use development environment which runs the same on Windows, Linux and Mac. \n\nOur development environment uses a virtual machine based on Ubuntu 24.04. The virtual environemnt is initialized with a [cloud-init](https://cloud-init.io/) script we provide. \n\nThe script installs [k3s](https://k3s.io/) as Kubernetes engine and [nix](https://nixos.org/download/#download-nix) to setup development environments. The project includes multiple subprojects, each one with a different set of dependencies so we use [direnv](https://direnv.net/) to automatically activate the right tools when you open a terminal.\n\nTo create a virtual machine in your workstation we use [multipass](https://multipass.run/). As an IDE we use [VSCode](https://code.visualstudio.com/) as it allows [Remote Development](https://code.visualstudio.com/docs/remote/remote-overview) within the virtual machine, and we provide a workspace for it.\n\nYou need a virtual machine with at least 8GB of memory and 4 VCPU so your development workstation probably needs at least 16GB and 6 VCPU. Your mileage may vary.\n\n*NOTE*: of course you can operate variations. It should be relatively easy to run the development virtual machine in a cloud provider using the provided cloud-init script. Basically all the cloud providers allows to build a VM using cloud-init.\nWe do not provide instructions how to setup on the various cloud provider (yet).\n\nYou can even setup the development environment by yourself without using the virtual machine, and use a different IDE, but adapting the configuration for your IDE is up to you and could be very time-consuming. Our development environment is the result of a few years of fine tuning, so we do not expect it will be easy to change.\n\n## Install Multipass\n\nHere we describe how to setup the development virtual machine on Linux, Mac and Windows using multipass. First, install multipass.\n\n- On Mac, if you already have [brew](https://brew.sh/), installing it is as easy as to type `brew install multipass`.\n\n- On Linux, if you already have [snap](https://snapcraft.io/), installing it is as easy as type `sudo snap install multipass`.\n\n- On Windows, you need Windows 10 Pro/Enterprise/Education v1803 or later, or any Windows 10 with VirtualBox. Make sure your local network is designated as private, otherwise Windows prevents Multipass from starting.\n\nDownload the multipass installer from [here](https://multipass.run/download/windows) and run the installer. Pick Hyperv in preference, VirtualBox as an alternative.\n\n- Alternative installation options are available [here](https://multipass.run/install)\n\n## Setup a development VM using multipass\n\nThe steps and the commands to install the development VM are the same in Linux, Windows and Mac.\n\nOnce you have `multipass` installed, open a terminal or powershell and type the following command:\n\n```\nmultipass launch -nopenserverless -c4 -d20g -m8g --cloud-init https://raw.githubusercontent.com/apache/openserverless/main/cloud-init.yaml\n```\n\nNow wait until the installation is complete and you see messages like `status: done` or `Launched: openserverless` (message can be different depending on multipass version effectively installed).\n\n```\nmultipass exec \"openserverless\" -- sudo cloud-init status --wait\n```\n\nFinally check if Kubernetes (k3s) is up and running in the VM:\n\n```\nmultipass exec openserverless sudo k3s kubectl get nodes\n```\n\nYou should see something like this:\n\n```\nNAME             STATUS   ROLES                  AGE     VERSION\nopenserverless   Ready    control-plane,master   4h58m   v1.29.6+k3s1\n```\n\n## Configure SSH access for VSCode\n\nTo access the virtual machine from VSCode you need to setup a ssh key and create a configuration. Open a terminal (powershell on Windows) and follow those steps:\n\n1. Check if you already have a key in `$HOME/.ssh/id_rsa`. If not, generate one with `ssh-keygen -t rsa` then press enter to confirm.\n\n2. Copy the key in the virtual machine to allow no password access:\n\n```\nmultipass transfer $HOME/.ssh/id_rsa.pub openserverless:\nmultipass exec openserverless -- bash -c \"cat id_rsa.pub | tee -a .ssh/authorized_keys\"\n```\n\n3. Create a configuration named `openserverless` to easily access it.\n\nFirst type `multipass list`. You will see something like this:\n\n```\nName                    State             IPv4             Image\nopenserverless          Running           10.6.73.253      Ubuntu 24.04 LTS\n                                          10.42.0.0\n                                          10.42.0.1\n```\n\nTake note of the `\u003cIP\u003e` in the `openserverless line` (in this case `10.6.73.253` but your value can be different)\n\nUse an editor to add to the file `~/.ssh/config` the following:\n\n```\nHost openserverless\n  Hostname  \u003cIP\u003e\n  User ubuntu\n  IdentityFile ~/.ssh/id_rsa\n```\n\n4. Check you have access without password:\n\n```\nssh openserverless\n```\n\nOnce you accessed the VM configure git with your username and email:\n\n```\ngit config --global user.name \"\u003cyour-name\u003e\"\ngit config --global user.email \"\u003cyour-email\u003e\"\n```\n\n## Access the virtual machine with VSCode\n\n1. Install [VSCode](https://code.visualstudio.com/)\n\n2. Type F1 then \"Install Extensions\" (or click on the task bar the package icon)\n\n3. Search \"remote ssh\" and install the extension \"Remote - SSH\"\n\n4. Type F1 then \"Connect\" (or click on the `\u003e\u003c` symbol in the corner to the left at the bottom) and select \"Remote-SSH: Connect Current Windows to Host\"\n\n5. Click on `openserverless` then select Linux if requested\n\n6. Click on the menu bar on `File` then `Openworkspace from file`, then select the `openserverless` folder and open one of the workspaces. Currently:\n\n- `openserverless-cli.code-workspace`: for the CLI along with task\n- `openserverless-operator.code-workspace`: for the Operator alone\n- `openserverless.code-workspace`: for the root with the Operator and the site\n\n\n Select `Linux` and then `Trust the authors` if requested.\n\n## Access to the subprojects\n\nNow you have all the repositories in your virtual machine and the subprojects. Furthermore, in the VM it is configured `nix` that will setup all the dependencies to develop the subprojects, and `direnv` that activates the right dependencies when you open the terminal in a subproject.\n\nFor example try to execute `Terminal \u003e New Terminal` and you will see you can choose the subproject. If you select `website` for example, the system will download all the dependencies to build the web site, in this case `hugo` and `npm` and install the required tools `postcss`.\n\n## Use Git Submodules\n\nApache OpenServerless uses git submodules.\n\nThis means in practice two things: you have to do Pull Requests and changes forking the subprojects individually.\n\nThen you have from time to time to update the whole subtree to the latest releases of all the subprojects.\n\n### Contributing to subprojects\n\nTo contribute to a subproject:\n\n- fork a subproject: for example `github.com/apache/openserverless-website` into `github.com/\u003cusername\u003e/openserverless-website`\n- add a remote to the subproject to point to your fork: for example after opening the `website` terminal, add `git remote add \u003cusername\u003e github.com/\u003cusername\u003e/openserverless-website`\n- now you can change the code and push in your fork: `git push \u003cusername\u003e main`\n- you can now contribute a Pull Request\n\n### Syncronize the tree\n\nOpen a terminal in the `root` subproject and type `./update-tree.sh`. This script will update all the subprojects to the latest available version on the main repo.\n\nDo not worry about contributing PR to update dependencies as the maintainers will periodically take care of this.\n\n## Cleanup\n\nIf you do not want to keep the VM anymore, ensure you have backed up all your files. Then remove it from your cloud provider (check your cloud provider documentation).\n\nFor multipass, use the following commands to cleanup:\n\n```\nmultipass delete openserverless --purge\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fopenserverless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fopenserverless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fopenserverless/lists"}