{"id":37117080,"url":"https://github.com/platform9/app-controller","last_synced_at":"2026-01-14T13:42:37.755Z","repository":{"id":43401467,"uuid":"431715353","full_name":"platform9/app-controller","owner":"platform9","description":"Backend service that interacts with the Kubernetes cluster using the Knative serving components.","archived":false,"fork":false,"pushed_at":"2022-03-31T06:42:26.000Z","size":214,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-06-21T01:40:37.865Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/platform9.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}},"created_at":"2021-11-25T04:38:50.000Z","updated_at":"2024-06-21T01:40:37.865Z","dependencies_parsed_at":"2022-09-06T23:20:53.276Z","dependency_job_id":null,"html_url":"https://github.com/platform9/app-controller","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/platform9/app-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platform9%2Fapp-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platform9%2Fapp-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platform9%2Fapp-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platform9%2Fapp-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/platform9","download_url":"https://codeload.github.com/platform9/app-controller/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/platform9%2Fapp-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28421773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T13:30:50.153Z","status":"ssl_error","status_checked_at":"2026-01-14T13:29:08.907Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-14T13:42:37.215Z","updated_at":"2026-01-14T13:42:37.747Z","avatar_url":"https://github.com/platform9.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## `app-controller`\n\nA backend service that interacts with the underlying Kubernetes cluster using the Knative serving components.\n\n## Pre-requisites\nTo start the app-controller backend service, pre-requisites are:\n\n1. Linux (Preferred)\n2. A kubernetes cluster installed with [knative serving components](https://platform9.com/blog/how-to-set-up-knative-serving-on-kubernetes/)\n3. Link to MySQL Database (local/remote) that acts as data store for app-controller.\n\n## Configurations\nThe configurations for the service are set using `config.yaml`. Sample of `config.yaml` is present at [etc/config.yaml](etc/config.yaml)\n\nThis config.yaml should be placed at `/etc/pf9/app-controller/config.yaml`, it contains: \n\n```\n# Path to the kubeconfig file of the underlying Kubernetes cluster that has Knative installed.\n1. kubeconfig path\n\n# Database name, username, password, URL, port. \n2. DB credentials\n\n# auth0 JWKS URL, client id.\n3. auth0 credentials\n\n# constraints on maximum apps deploy count, replical count.\n4. constraints (optional)\n```\n\n## Build app-controller\n\nClone the repository, navigate to the cloned repository and download the dependencies using `go mod download`. Before building, ensure the `config.yaml` is configured accordingly and placed at required location.\n\nTo build the app-controller binary, use the below command, app-controller binary built using make is placed in `bin` directory.\n\n```sh\n# Using make, prefered for linux OS.\nmake build\n\n# Using go build and run.\nsudo go run cmd/main.go\n```\n\n### For DB Schema changes or first time builds\nIf DB Schema is changed or for first time builds, then to generate updated `pkgs/db/migrations_generated.go`, follow the below commands, before building the binary.\n\n```\ngo get -u 'go get -u github.com/go-bindata/go-bindata/...'\n\n# Set the path where go-bindata binary is installed.\nexport PATH=${PATH}:${GOPATH}/bin\ncd pkg/db; go generate; cd -\n```\n\n## Run app-controller service\n\n`app-controller` service can be run using binary and as a system service on linux machine.\n\n### Using binary\nTo run app-controller through binary, follow the below command:\n```sh\n# Initialize and upgrade database.\n./bin/app-controller migrate\n\n# Start the app-controller service.\n./bin/app-controller\n```\n\n### Using system service file (Preferred)\nTo run app-controller as a system service, service file [appcontroller.service](appcontroller.service) should be place at `/etc/systemd/system/` directory and app-controller binary at `/usr/bin/app-controller/` directory. To start the service follow the below commands:\n\n```sh\n# Start the app-controller service.\nsudo systemctl start appcontroller.service\n```\n\n`app-controller` service will be now up and running, to check the latest status of service:\n\n```sh\n# Check the status of app-controller service.\nsudo systemctl status appcontroller.service\n\nSample Output:\n● appcontroller.service - App Controller Service\n   Loaded: loaded (/etc/systemd/system/appcontroller.service; disabled; vendor preset: enabled)\n   Active: active (running) since Mon 2022-02-21 10:39:19 UTC; 12s ago\n Main PID: 9144 (app-controller)\n    Tasks: 16\n   Memory: 9.4M\n      CPU: 1.823s\n   CGroup: /system.slice/appcontroller.service\n           └─9144 /usr/bin/app-controller/app-controller\n\nFeb 21 10:39:19 platform9 systemd[1]: Started App Controller Service.\n``` \n\n\n* Logs for app-controller service can be found at `/var/log/pf9/app-controller/app-controller.log`\n\n## `app-controller` APIs\nTo interact with the app-controller service, app-controller APIs are needed. This requires an Auth0 token.\n\n```sh\n# To get list of apps for a user.\ncurl --request GET --url 'http://\u003cservice endpoint\u003e:6112/v1/apps'  --header \"Authorization: Bearer ${AUTH0_IDTOKEN}\" | jq .\n\n# To describe an app by name.\ncurl --request GET --url 'http://\u003cservice endpoint\u003e:6112/v1/apps/\u003cname\u003e'  --header \"Authorization: Bearer ${AUTH0_IDTOKEN}\" | jq .\n\n# To create an app, where name is app name, image is container image of app, envs is environment variables with key:value pairs list, port is container port to access app.\ncurl --request POST --url 'http://\u003cservice endpoint\u003e:6112/v1/apps'  --header \"Authorization: Bearer ${AUTH0_IDTOKEN}\" --data '{\"name\": \"\u003cappname\u003e\", \"image\": \"\u003ccontainer image\u003e\", \"envs\": [{ \"key\":\"\u003ckey\u003e\", \"value\":\"\u003cvalue\u003e\"}], \"port\": \"\u003cport\u003e\"}'\n\n# To delete an app by name.\ncurl --request DELETE --url 'http://\u003cservice endpoint\u003e:6112/v1/apps/\u003cname\u003e'  --header \"Authorization: Bearer ${AUTH0_IDTOKEN}\"\n\n- If service is deployed locally, then can replace service endpoint with 127.0.0.1\n```\n\n## Fetching Auth0 token\nAuth0 token can be fetched using Auth0 APIs. There are 3 steps to get the [auth0 id token](https://auth0.com/docs/quickstart/native/device).\n\n1. Request device code\n2. Device activation\n3. Request auth0 token\n\n### **Pre-requisites**\n* [auth0 native application](https://auth0.com/docs/get-started/auth0-overview/create-applications/native-apps)\n* [auth0 device code setup](https://auth0.com/docs/quickstart/native/device#prerequisites)\n\n#### [**Request device code**](https://auth0.com/docs/quickstart/native/device#request-device-code)\n\n```sh\n# Request device code \ncurl --request POST \\\n  --url 'https://YOUR_DOMAIN/oauth/device/code' \\\n  --header 'content-type: application/x-www-form-urlencoded' \\\n  --data 'client_id=YOUR_CLIENT_ID' \\\n  --data 'scope=YOUR_SCOPE' \n```\n- Basic sample scope is 'scope=profile email openid'\n\n#### **Device activation**\nUpon request for device code, the [sample device code](https://auth0.com/docs/quickstart/native/device#device-code-response) response will be:\n```sh\n{\n  \"device_code\": \"Ag_EE...ko1p\",\n  \"user_code\": \"QTZL-MCBW\",\n  \"verification_uri\": \"https://accounts.acmetest.org/activate\",\n  \"verification_uri_complete\": \"https://accounts.acmetest.org/activate?user_code=QTZL-MCBW\",\n  \"expires_in\": 900,\n  \"interval\": 5\n}\n```\n\nThen open `verification_url_complete` in browser, obtained from device code response to complete the device activation. \n\n#### [**Request auth0 token**](https://auth0.com/docs/quickstart/native/device#example-request-token-post-to-token-url)\n\nOnce device activation is successful, then request for auth0 token using below command.\n```sh\n# Use the device code received from device code response\ncurl --request POST \\\n  --url 'https://YOUR_DOMAIN/oauth/token' \\\n  --header 'content-type: application/x-www-form-urlencoded' \\\n  --data grant_type=urn:ietf:params:oauth:grant-type:device_code \\\n  --data device_code=YOUR_DEVICE_CODE \\\n  --data 'client_id=YOUR_CLIENT_ID'\n```\n\nThe response will contain both, access_token and id_token. We use auth0 `id_token` to authorize the user through app-controller. To access the app-controller APIs seamlessly export the auth0 `id_token`. \n\n```sh\n# Replace the \u003cid_token\u003e with the id_token value received from request auth0 token.\nexport AUTH0_IDTOKEN=\"\u003cid_token\u003e\"\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplatform9%2Fapp-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplatform9%2Fapp-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplatform9%2Fapp-controller/lists"}