Install app

POST/api/install/{app}

Writes the app's compose file under ~/.homebutler/apps/<app> and starts it. Protection: token. A failed pre-flight check, such as a port that is taken, returns 200 with status set to failed and the reasons in issues, so you can change the port and ask again.

Authorizations

Authorizationstringheaderrequired

The token you start the server with: homebutler serve --token <token>, or web.token in the config file. Send it as Authorization: Bearer <token>. When the server has a token, every /api/ route except the CORS preflight requires it, reads included.

Path parameters

appstringrequired

The app name from List apps.

Example: it-tools

Body

application/json

portstring

The host port, as a string. It defaults to the app's default_port. A JSON number in its place is ignored, and the app installs on the default port.

Example: 18620

Response

200 · application/json

status is installed, or failed with issues.

statusstringrequired

What happened.

Available options: installedfaileduninstalledpurged

appstringrequired

The app name.

issuesstring[]

Why a pre-flight check failed. Present when status is failed.

portstring

The host port.

pathstring

The folder with the app's compose file and data.

statestring

The containers' state after the install.

data_preservedboolean

true after an uninstall, false after a purge.

warningstring

Present when an earlier install's state couldn't be carried over, or when part of the data is in Docker volumes outside the app directory.

kept_volumesstring[]

Volumes that still exist after a purge. Present only when not empty.

unchecked_volumesstring[]

Volumes Docker couldn't be asked about during a purge. Present only when not empty.

cURLcURLPythonJavaScript

curl --request POST \
  --url 'http://localhost:8080/api/install/{app}' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "port": "18620"
}'

{
  "status": "installed",
  "app": "it-tools",
  "port": "18620",
  "path": "/home/you/.homebutler/apps/it-tools",
  "state": "running"
}