Skip to content

removed projector from workspace apps, replaced with http server #889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 14, 2022
Merged

removed projector from workspace apps, replaced with http server #889

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f99b8ca
removed projector from workspace apps, replaced with http server
sharkymark Mar 12, 2022
21ceb6a
chore: edit text
Mar 14, 2022
1dbef2a
chore: fix manifest
Mar 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,6 @@
{
"path": "./workspaces/lifecycle.md"
},
{
"path": "./workspaces/applications.md"
},
{
"path": "./workspaces/autostart.md"
},
Expand Down Expand Up @@ -86,6 +83,9 @@
{
"path": "./workspaces/vs-code-extensions.md"
},
{
"path": "./workspaces/applications.md"
},
{
"path": "./workspaces/workspace-params.md"
},
Expand Down
55 changes: 38 additions & 17 deletions workspaces/applications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,32 @@
---
title: "Applications"
title: "Workspace applications"
description: Learn how to access web apps running in your workspace.
state: beta
---

You can connect to web applications installed on your workspace using the
You can connect to web applications installed on your workspace using an
applications specification file located at `/coder/apps/config.yaml` of the
workspace filesystem.

![Application Launcher](../assets/workspaces/applications.png)

## Enabling custom apps
## Enabling workspace applications

If you'd like to use custom apps in Coder, you can enable this feature in the
UI:
If you'd like to use workspace applications in Coder, you can enable this
feature in the UI:

1. In the top-right, click on your avatar and select **Feature Preview**.
1. Click **Workspace applications** and select **Enable**.

## Application specification file

To define custom applications, add a configuration file at
To define workspace applications, add a configuration file at
`/coder/apps/config.yaml` to your image.

The config file specifies the parameters Coder requires in order to launch the
application. Within the file, you can specify the following for each
application:
The config file specifies the parameters Coder requires to launch the
application. Here is a sample `config.yaml` for adding a Python HTTP server as a
workspace application. Note that this requires the `python3` binary, which is
included in Coder's base images.

```yaml
# /coder/apps/config.yaml
Expand All @@ -34,23 +35,23 @@ apps:
# Name of application in launcher. Name may consist of alphanumeric
# characters, dashes, underscores. Names must begin with an alphanumeric
# character. Names must be unique per application. Required.
- name: projector
- name: HTTP server
# Application scheme - must be http or https. Required.
scheme: http
# Application port. Required.
port: 9999
port: 8000
# Host of the application to use when dialing. Defaults to localhost.
# Optional.
host: "localhost"
# Working directory for the start command. Required.
working-directory: /home/coder
# File path to icon used in application launcher. Icons should be either
# PNG, SVG, or JPG. Required.
icon-path: /home/coder/goland.svg
icon-path: /home/coder/python-logo.png
# Command to start the application. Required.
command: /home/coder/.local/bin/projector
command: python3
# Array of arguments for command. Optional.
args: ["run"]
args: ["-m", "http.server"]
# Health checks to get running application status. Can use exec or http
# health checks to localhost. Optional, but we recommend specifying a
# health check. If you don't supply one, then an http request is sent to
Expand All @@ -59,7 +60,7 @@ apps:
# Exec commands require an exit code of '0' to report healthy.
exec:
command: "pgrep"
args: ["projector"]
args: ["python3"]
# http sends a GET request to the address specified via the parameters.
# Expects the status codes to match; default is HTTP 200.
http:
Expand All @@ -71,24 +72,44 @@ apps:
host: "localhost"
# Port to use when dialing the application. If not specified it
# inherits the application port. Optional.
port: 9999
port: 8000
# Path to use for the health check. If not specified defaults to
# "/". Optional.
path: "/healthz"
path: ""
```

**Notes**:

- A health check _must_ report healthy for you to access the application.
- If you specify both the HTTP and Exec health checks, Coder prioritizes HTTP.

### Image creation

When creating your image, be sure to:

1. In the folder where your Dockerfile is, add a `coder/apps` folder
1. Add the `config.yaml` you created to `coder/apps`.
1. Add the icon that you would like Coder to render for your app to the
`coder/apps` folder
1. Add a step to your Dockerfile to copy the `coder` folder into the image:

```text
# copy custom apps info (config.yaml)
COPY ["./coder", "/coder"]
```

## Sample usage

Coder offers an [image](https://hub.docker.com/r/codercom/enterprise-vnc) that
helps you [set up a VNC](../guides/customization/vnc.md). With a VNC available,
you can add an icon to your **Browser applications** via setting the
[config file](https://github.com/coder/enterprise-images/blob/91ef8f521b2275783fed54b27052cc544153cd99/images/vnc/coder/apps/config.yaml).

You are welcome to try the
[public Dockerfile repo that contains the example above](https://github.com/mtm20176/dockerfiles/tree/main/python/workspace-apps).
The repo includes config files that set up Python and Node.js HTTP servers and
the accompanying icons.

You can also see our
[blog post](https://coder.com/blog/run-any-application-or-ide-in-coder) for
further samples on adding tools like Portainer, Insomnia, and various versions
Expand Down