Hello Universe is a demo application intended for learning about Palette and to help showcase product features.
Get started with Hello Universe by choosing between two deployment approaches; docker or a non-docker-based approach.
Hello Universe is available as a Docker image. To run Hello Universe issue the following commands:
docker pull ghcr.io/spectrocloud/hello-universe:1.1.0
docker run -p 8080:8080 ghcr.io/spectrocloud/hello-universe:1.1.0To run locally without Docker:
git clone [email protected]:spectrocloud/hello-universe.git
npm ci
npm run start
Hello Universe accepts the following environment variables:
| Variable | Description | Default |
|---|---|---|
| API_URI | The fully qualified hostname and port of the API server. In a reverse proxy setting this can be the application loadbalancer. | "" |
| API_VERSION | The API version number. | 1 |
| SVC_URI | The URI to the service API, such as the internal Kubernetes container hostname of the API service. | "" |
| TOKEN | The API authorization token. This is only used if the API is configured for authorization. | "" |
Hello Universe's capabilities can be expanded if connected to the Hello Universe API. To connect Hello Universe to the API server, provide the API server's fully qualified hostname and port as an environment variable value. Be aware that the API server requires an available Postgres database. Checkout Hello Universe DB for a dockerized Postgres instance ready for integration with the Hello Universe API.
API_URI=http://localhost:3000If you are using the Docker image then use the -e flag parameter.
docker run -p 8080:8080 -e API_URI=http://localhost:3000 ghcr.io/spectrocloud/hello-universe:1.2.0A Docker container with a reverse proxy is available. The reverse proxy is usefull for scenarios when you need to deploy the
hello universe application into a Kubernetes cluster or similar architectures and need the UI to route requests internal to the hosting platform. An example of such behavior is needing to to reach a private API inside the Kubernetes cluster. The reverse proxy expects the API to be listening on port 3000.
docker run -p 8080:8080 -p 3000:3000 -e SVC_URI="http://myprivate.api.address.example:3000" -e API_URI="http://myloadbalancer.example:3000" ghcr.io/spectrocloud/hello-universe:1.2.0-proxy| Variable | Description | Default |
|---|---|---|
SVC_URI |
The URI to the service API, such as the internal Kubernetes container hostname of the API service. | "" |
API_URI |
The fully qualified hostname and port of the API server. In a reverse proxy setting, set this to the service loadbalancer. If QUERY_K8S_API set to true, leve this parameter empty. |
"" |
TOKEN |
The API authorization token. This is only used if the API is configured for authorization. | "" |
QUERY_K8S_API |
Set to true to query the Kubernetes API for the service hostname. This is useful when the service is deployed in a Kubernetes cluster. |
false |
To deploy the Hello Universe application into a Kubernetes cluster, use the deployment manifest in deployments/k8s.yaml. Ensure you provide values and update all placeholders in the manifest with the value <REPLACE_ME>. The values must be in base64 format.
In a Kubernetes environment, you can use two methods to deploy the Hello Universe application:
- Use a single load balancer for the UI and API services.
- Use separate load balancers for the UI and API services.
When deploying the Hello Universe application into a Kubernetes cluster, set the QUERY_K8S_API environment variable to true and set the API_URI environment variable to an empty string. This will result in the reverse proxy forwarding API requests to API service. Only a single load balancer is used in this deployment pattern. If authorization is enabled, provide the auth-token Kubernetes secret with the API authorization token value. Otherwise, API will fail to authorize requests.
Note
The QUERY_K8S_API environment variable is only used when deploying the Hello Universe application into a Kubernetes cluster. Enabling this environment variable will query the Kubernetes API for the service hostname. You can review the script in the scripts/service-ip.sh.
Inside the Hello Universe container, Caddy is used as a reverse proxy to route requests to the API server. The API server is expected to be listening on port 3000.
If the Hello Universe API is enabled for authorization, provide the TOKEN environment variable with the API authorization token. The default anonymous token is "931A3B02-8DCC-543F-A1B2-69423D1A0B94". The reverse proxy will include the token when forwarding requests to the API server.
![TIP] If you want to automatically inject the authorization token into the reverse proxy for all API requests, uncomment line 29 in the Caddyfile under /etc/caddy/.
header_up Authorization "Bearer {$TOKEN}"Issue the commandcaddy reload --config /etc/caddy/Caddyfileto apply the changes.
![WARNING]
This deployment pattern will not work in single deployment. You need to deploy the API and UI services separately due to the dependency on the API service. Use the signle deployment pattern if you want to deploy the services together.
To use separate load balancers for the UI and API services, you need to make the following changes to the Kubernetes deployment manifest. Change the API service type to LoadBalancer. The API service will have its own load balancer, and you will need to set the UI's API_URI environment variable to the fully qualified hostname and port of the API service.
apiVersion: v1
kind: Service
metadata:
name: api
namespace: hello-universe
spec:
selector:
app: api
ports:
- protocol: TCP
port: 3000
targetPort: 3000
type: LoadBalancerFor the UI service, change the image to the default Hello Universe image.
containers:
- name: ui
image: ghcr.io/spectrocloud/hello-universe:1.1.2
imagePullPolicy: Always
ports:
- containerPort: 8080
name: uiThe UI service will have its own load balancer, and you will need to set the API_URI environment variable to the fully qualified hostname and port of the API service. Leave the QUERY_K8S_API environment variable set to false, and set SVC_URI to an empty string.
API_URI=http://<EXTERNAL_IP>:3000
SVC_URI=""
QUERY_K8S_API=falseIf authorization is enabled, provide the auth-token Kubernetes secret with the API authorization token value. Otherwise, API will fail to authorize requests.
We sign our images through Cosign. Review the Image Verification page to learn more.
Create an environment file .env file and add the following values:
REACT_APP_API_URI=http://localhost:3000
REACT_APP_API_VERSION=1
The .env file is how you point to the local development API server. Otherwise, local browser storage is used.
Use the docker-compose.yml to start the required services.
make start-servicesNext, start the local development server
make startTo stop the docker containers, use the following command.
make stop-servicesTo remove the build folder use the command make clean
To build the hosting assets use the command make build
To start the local development server without a proxy use the command make start.
To start the Caddy server without a reverse proxy use the command make start-prod.
To start the Caddy server with a reverse proxy use the command make start-proxy.
- Caddy
- React Spring is used to animate the logo.