This package provides a CLI client and a node library for interacting with Wonderland Cloud services.
wl-cloud [resource] [command] ... [--help | -h]
The following resources are available:
- server
- page
- subscription
- api
...
Here are some common examples on how to use the CLI tool:
wl-cloud server debug <your-server-name>
This command will connect to your custom server via web sockets and
forward all console.log
messages of your custom server to your local
console.
It also listens to file changes in your custom server code directory and automatically packs, uploads, and restarts your server on change.
You can set the needed configuration values either via command line argument or via environment variables.
To authenticate, place the downloaded token file from the
Wonderland Engine Account page
into your project folder and rename it to wle-apitoken.json
.
Never commit this file to your version control, keep it local only.
The wl-cloud
command will automatically find it and authenticate.
wl-cloud server update <your-server-name>
This command will pack and upload the local server project and deploy it to your server at given server URL.
This command allows you to publish your Wonderland Engine project as a static page deployment which will be hosted by
us. When you execute the command for the first time, a local deployment.json
file will be created in your work
directory or by specifying the config location via the --config=yourConfigPath
. If a config file is present, it will
always be used first and the command arguments for project-name
and projectLocation
will be ignored. To explicitly
create a new project deployment instead of overwriting the existing deployment, provide a new --config
path.
Once you have an existing config, you can also change the access
or withThreads
flag inside your config file and use
it to update you already existing project.
[!NOTE] When creating a new project deployment, a page domain with new SSL certs is provisioned. As stated by Google, the SSL certs provisioning process can take up to 24h, so please be patient, if everything worked successfully, the custom domain usually works within max 30 minutes after creation.
-
create your-page-name ./path/to/deploy --access unlisted|public [--noThreads]
Creates a new page with theyour-page-name
name from./path/to/deploy
with either public or unlisted access. Name and path are mandatory for creating. if you add the--noThreads
flag, the additional response headers for enabling the WLE threads feature are omitted -
update [your-page-name] ./path/to/deploy
Updates an existing page -
list
List all of your pages -
delete your-page-name
Deletes your page -
get your-page-name
Load remote page state and info
It is recommended to use relative paths for the deployment location and the config locations. This way you can easily share the projects pages configurations via collaborative software versioning tools such as git or SVC.
For example, you could have 2 project deployed, one public for production and one private for development preview. In
this example we expect, that a wle-apitoken.json
file is present in the work directory. It is strongly advised to add
this file to your .gitignore
file and inject it via environment variables in your CLI, a simple shell script for this
could look like this:
cat ./wle-apitoken.json | base64
echo $WLE_API_TOKEN_BASE64 | base64 -d > ./wle-apitoken.json
Production:
export PAGE_CONFIG_LOCATION=./projectConfigs/prod.json && export ACCESS=public && npm exec wl-cloud page create my-fancy-project ./deploy
Development
export PAGE_CONFIG_LOCATION=./projectConfigs/dev.json && export ACCESS=unlisted && npm exec wl-cloud page create my-fancy-project ./deploy
The visibility settings for the pages are set when initially creating the page and are retained on page updates.
{
"scripts": {
"publish:prod": "wl-cloud page update --config ./projectConfigs/prod.json",
"publish:dev": "wl-cloud page update --config ./projectConfigs/dev.json"
}
}
deploy-production:
image: wonderlandengine/editor:latest
stage: deploy
before-script:
- echo $WLE_API_TOKEN_BASE64 | base64 -d > ./wle-apitoken.json
script:
- npm i
- WonderlandEditor --windowless --credentials "$WLE_CREDENTIALS" --package --project ./MyFancyProject.wlp
- npm run publish:prod
cache:
key: ${CI_COMMIT_REF_SLUG}
paths:
- cache/
artifacts: [ ]
rules:
# only run pipeline on default branch changes
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: on_success
# Avoid downloading artefacts
needs: [ ]
- --config path (optional) specify the location of your config file for publishing
- --access public | unlisted (optional) allow listing your page in the public page explorer
Authentication is done either via --authToken
argument option or via a wle-apitoken.json
in your work directory.
npm exec wl-cloud page create my-fancy-project ./deploy
export WLE_CREDENTIALS=YOUWLAPITOKEN && npm exec wl-cloud page create my-fancy-proejct ./deploy
{
"scripts": {
"page:new": "wl-cloud page create my-fancy-project ./deploy"
}
}
This command will upload and publish the Wonderland Engine project page with the name my-fancy-project
in the
relative ./deploy
directory. Once the project is published and deployed, a deployment.json
with the
actual projectName
, the absolute projectLocation
, a flag if the project is public isPublic
, the full project url
of the GCP bucket fullProjectUrl
and your custom domain projectDomain
will be created. If no --access
type flag is
provided then project page will either use the value from the existing deployment.json
or will default to unlisted
,
meaning that the page cannot be found in the UI via the page explorer
.
ACCESS=public && npm exec wl-cloud page create my-fancy-proejct ./deploy
{
"scripts": {
"project:new": "wl-cloud page create my-fancy-project ./deploy --access unlisted"
}
}
export ACCESS=public && export PAGE_CONFIG_LOCATION=./deployments/production.json && npm exec wl-cloud page create my-fancy-proejct ./deploy
export ACCESS=unlisted npm exec wl-cloud page update
Example usage (change existing project (config json in provided config location) access type to public)
export ACCESS=public && export PAGE_CONFIG_LOCATION=./config/example-config.json && npm exec wl-cloud page update
npm exec wl-cloud api create my-api-name 80 strm/helloworld-http env1=value1,env2=value2
This command will create a hello world application listening on port 80
with the image strm/helloworld-http
and the environment values env1=value1
and env2=value2
.
If you want to change or add env values to your current api deployment, you can do this via the command below. Please note, that existing env vars will be overwritten.
npm exec wl-cloud api update my-api-name env env1=value1,env2=value2
The parser also supports env vars with comma separated values as in the example below
npm exec wl-cloud api update my-api-name env env1=value1,env2=inner1,inner2,inner3
If you want to remove all env vars and only add the provided ones, use example below
npm exec wl-cloud api update my-api-name env env1=value1,env2=value2 --updateEnv=false
If you want to change the port value, you can use the command below
npm exec wl-cloud api update my-api-name port 1234
If you want to change the used image, use the command below. This will trigger a new deployment. Please note, that if the pod fails to start, a rollback to the previously working version is being performed.
npm exec wl-cloud api update my-api-name image my-image-registry.com/my-image-name:tagname
If you want to change the docker secret for your private registry you can do this with the command below.
npm exec wl-cloud api update my-api-name dockerConfigBase64 my-image-registry.com/my-image-name:tagname
If you want to use a private docker registry, then you need to provide a docker login secret encoded in base64. You can generate one by using this command.
kubectl create secret docker-registry --dry-run=true docker-regcred \
--docker-server=https://index.docker.io/v1/ \
--docker-username=xxx \
--docker-password=xxx \
--docker-email=yourmail@yourdomain.com \
-o yaml > docker-secret.yaml
This will generate a .yaml
file with the following content
apiVersion: v1
data:
.dockerconfigjson: eyJhdXRocyI6eyJodHRwczovL2luZGV4LmRvY2tlci5pby92MS8iOnsidXNlcm5hbWUiOiJ4eHgiLCJwYXNzd29yZCI6Inh4eCIsImVtYWlsIjoieW91cm1haWxAeW91cmRvbWFpbi5jb20iLCJhdXRoIjoiZUhoNE9uaDRlQT09In19fQ==
kind: Secret
metadata:
creationTimestamp: null
name: docker-regcred
type: kubernetes.io/dockerconfigjson
Then you can copy the value for .dockerconfigjson
and use it as the 4th argument when creating an api:
npm exec wl-cloud api create my-api-name 80 strm/helloworld-http eyJhdXRocyI6eyJodHRwczovL2luZGV4LmRvY2tlci5pby92MS8iOnsidXNlcm5hbWUiOiJ4eHgiLCJwYXNzd29yZCI6Inh4eCIsImVtYWlsIjoieW91cm1haWxAeW91cmRvbWFpbi5jb20iLCJhdXRoIjoiZUhoNE9uaDRlQT09In19fQ
Creating an api with env vars and docker config api.ts
npm exec wl-cloud api create my-api-name 80 strm/helloworld-http env1=value1,env2=value2 eyJhdXRocyI6eyJodHRwczovL2luZGV4LmRvY2tlci5pby92MS8iOnsidXNlcm5hbWUiOiJ4eHgiLCJwYXNzd29yZCI6Inh4eCIsImVtYWlsIjoieW91cm1haWxAeW91cmRvbWFpbi5jb20iLCJhdXRoIjoiZUhoNE9uaDRlQT09In19fQ
If you want to add a new api route to a page deployment, you need to have the Pages with Apis
subscription.
Then you can run this command to deploy your my-api-name
at my-api-path
on your page-name
. The skipPrefix
value is optional and is
false
per default. By setting stripPrefix
to true
, the api path will be removed from the forwarded request url.
npm exec wl-cloud page add-api page-name my-api-name my-path [skipPrefix]
Example router with stripPrefix
set to false
for an api on api path example-api-path
router.get('/example-api-path/hello-world', (req, res) => res.status(200).json({message: 'hello world'}));
Example router with stripPrefix
set to true
for an api on api path example-api-path
router.get('/hello-world', (req, res) => res.status(200).json({message: 'hello world'}));
This will publish your api on the https://page-name.cloud.wondeland.dev/my-path
url.
To remove an api route from a page you can use this command.
wl-cloud page delete-api page-name my-api-name
Wonderland Cloud is a set of cloud services specialized for 3D and XR web experiences, provided by Wonderland.
The available services provided include multi-user servers optimized for 3D and VR web apps, as well as free 3D web app hosting.