What are servers?

A server defines the protocol port of a process that runs in a machine. It has a name, path, and attributes. The path defines the base path of the service that is used by the server. Attributes are optional and can be used to tune the server or for identification. You can add a server when you need to access a process in your workspace machine.

To add a server, use the User Dashboard or edit the workspace machine configuration YAML file.

The following is an example of the YAML file:

"node": {
    "port": "3000",
    "protocol": "http",
    "path": "/",
    "attributes": {}
}

The following is an example of the User Dashboard:

servers dashboard

If your workspace is running, saving a new server restarts the workspace.

Preview URLs

Adding the server with port 3000 does not mean you can use this port to access a server. Each server is assigned a URL when a workspace is running.

  • On Docker, port 3000 is published to a random port from the ephemeral port range from 32768 to 65535. The server URLs change every time you start a workspace.

  • On OpenShift, a route bound to a service is created. Routes are persistent URLs.

Getting preview URLs

In this example, you added a server with port 3000 and started a workspace. The following are ways to get the server’s preview URL:

  • Use a macro command.

  • In the IDE, Click the + icon in the bottom panel under the editor.

servers
  • In the User Dashboard, click Workspaces > YourWorkspace > Servers.

You can also see internal server URLs. Internal servers launch when the workspace container or pod is available.

Exposing internal servers

To access a port internally within a workspace, expose it internally, but do not make it publicly accessible. For example, a database server is exposed only for the web application and because of security concerns, it should not be accessible publicly. The database server is exposed as internal.

To expose a server as internal, add the corresponding attribute into the server configuration YAML file:

"db": {
    "port": "3200",
    "protocol": "tcp",
    "attributes": {
        "internal": "true"
    }
}

The application is able to fetch the database URL from the workspace runtime and access the database. The database URL is not accessible publicly from the browser.

Exposing secure servers

Secure servers are exposed publicly but access is restricted only for users who have permissions to the workspace. The authentication proxy is set up as the exposed server and the machine token is required to request it.

To expose a server as secure, add the corresponding attributes into the server configuration YAML file:

"tooling": {
    "port": "4921",
    "protocol": "http",
    "attributes": {
        "secure": "true",
        "unsecuredPaths": "/liveness",
        "cookiesAuthEnabled": "true"
    }
}

The following describes the attributes:

secure

Indicates whether the server is exposed as secure. The default value is false.

unsecuredPaths

Configures the secure servers. It contains a comma-separated list of URLs that are considered non-secure on the given server and can be accessible without a token. It may be needed when the server provides any public APIs. The API endpoint for health checks is an example.

cookiesAuthEnabled

Indicates whether cookies should be searched for a token. By default, it is disabled. You can enable this attribute if you are sure that servers cannot be attacked by Cross-Site Request Forgery (CSRF) or have special protection from it.

This is in the beta phase and disabled by default. See Secure servers for information on how to enable secure servers.