Web Component

Preparation

You should have a small app ready that is running on a web browser. E.g. something with:

• Python Streamlit
• R/Shiny
• Vue.js

Your application should have a working Dockerfile.

Create a web Component in Project Manifest

If you have a working web application, Pergola allows you to publish it right away. You just need to define a corresponding Component in your pergola.yaml.

A basic Component without any web related details looks like this:

version: v1

components:
- name: my-web-component
  docker:
    file: Dockerfile

So far, it is runnable, but you cannot reach it via your browser. Why? Because:

• There is no entry point, you need a URL (https​://something...) that points to your running application.
• Pergola protects its Components, you must specify that network requests are allowed.

Define web entry point

In order to access your application via a browser, it must be available within your Project's network and have a URL that is secured by HTTPS and proper TLS certificates. Pergola takes care of everything necessary, you only need to define an 'ingress' (aka entry point).

Just add an ingresses property to your pergola.yaml with a subproperty host and your chosen name, like:

[...]
  ingresses:
  - host: superdashboard

An ingress needs at least a host-name, that will become part of the generated URL. Pergola takes care of certificates, encryption, DNS routing, load balancing and all the other nerdy but important details.

The example above will lead Pergola to create a secured network path to your running app, reachable via https​://superdashboard-PROJECT-STAGE.apps.YOUR-PERGOLA-DOMAIN. For example:

https​://superdashboard-playgroundproject-dev.apps.pergola.mycompany.com

For reference, please see Ingress in Project Manifest.

Allow inbound requests to your Component

The Component needs to accept incoming traffic from the entry point (ingress) defined earlier. By default, all traffic is blocked for security reasons.

You need:

[...]
  ports:
  - 8080

This will publish port 8080 of your Component. Pergola will automatically link the earlier defined ingress to this port at release. Please note that the ports property generally allows other Components to communicate with each other within the Project's network, regardless if you have an ingress defined or not.

If your Component publishes more than one port - e.g. your Component provides multiple services, like web-frontend on port 8080 and an API on 8081 - you will need to map the ingress to one port explicitly. For example:

[...]
  ingresses:
  - host: superdashboard
    port: 8080
  ports:
  - 8080
  - 8081 

For reference, please see Ports in Project Manifest.

note

Configuration within the Project Manifest is independent of your application's code by design. You need to make sure that your app actually serves these ports as well, if not already done by the framework or the base container image you use.

For example, if you are using Streamlit, your Dockerfile's ENTRYPOINT could read as follows:

ENTRYPOINT ["streamlit", "run", "streamlit_app.py", "--server.port=8080", "--server.address=0.0.0.0"]

The server.address=0.0.0.0 option of Streamlit enables your app to accept traffic (here on port 8080) from outside the container. Otherwise, it will only listen on localhost and neither access via an ingress, nor from another Component within your Project will work.

Please consult the documentation of your web framework or the base container image on how to configure listener address and port.

Final pergola.yaml

Putting it all together, a fully working pergola.yaml could look like this:

version: v1

components:
- name: my-web-component
  docker:
    file: Dockerfile
  resources:
    cpu: 1000m
    memory: 2Gi
  ingresses:
  - host: superdashboard
  ports:
  - 8080

For a full reference of pergola.yaml, please see Project Manifest.