How to use WeWeb Server API

weweb-server

Pre-requisite

You will need a WeWeb subscription to have access to this server and to be able to configure it. Contact WeWeb team to subscribe to the "Self-Hosting" plan at https://www.weweb.ioopen in new window.

Principle

weweb-server will be the entry point of you self-hosted WeWeb project : it will manage Authentication, pages accesses and file serve for one or multiple of your WeWeb projects.

weweb-server needs to be connected to a Postgres Database that you will also have to host. We advise you to add a CDN in front of this server to keep some files in cache.

weweb-server needs some storage to retreive your projects' files. This storage can be local, distant or an AWS S3 bucket.

Each time you publish a new version of one of your projects, you will need to update the project's files and configure the server's DB info using WeWeb's Dashboard (The configure button can be found in the project's Dashboard > Self-Hosting > Configure WeWeb Server)

Note : weweb-server needs to be accessible from our servers so that we can send some configuration data to it each time you publish a project.

Database

You need to create a new Postgres Database that will be used by this server to store some non sensible data about your projects' pages (private accesses, user groups and a list of all pages). You will need to set some environment variables in weweb-server for it to be able to connect to the Database.

Storage

You will need some storage to put your projects' files on it.

This storage can be :

  • Local to weweb-server (add a folder in the server)
  • Distant (in some http url)
  • AWS S3 Bucket (the bucket doesn't need to be dedicated to this storage)

The storage location is configured using environment variables.

Environment variables

Main variables :

Varible nameRequiredDefaultValuesDescription
NODE_ENVYes-productionMust be set to production
FILES_PATHYes--Path of a frontend project's files in your storage. More information
PUBLIC_KEYYes--Can be found in WeWeb Dashboard > Workspace > Self-Hosting
PRIVATE_KEYYes--Can be found in WeWeb Dashboard > Workspace > Self-Hosting
PORTNo80-Port where weweb-server should run
SERVER_PATHNo--Sub path for your server url. Not required if your server url is an IP or a domain name. More information
WW_LOG_LEVELNotracefatal, error, warn, info, debug, traceLogs weweb-server should display
HIDE_VERSIONNo-false, trueHide server version from API calls and logs. Warning : This will prevent you to use the Dashboard interface with your server, and force you to use weweb-server API.

FILES_PATH :

For local storage, FILES_PATH should start with ./ else distant storage will be used. You can use two variables in the path that can be found in the name of the ZIP of the project :

  • :projectId
  • :filesVersion

Ex: ./projects/:projectId/:filesVersion will fetch the frontend project's files localy. FILES_PATH should end without a / .

SERVER_PATH :

If you setup something like https://my-domain.com/servers/weweb-server/ as WeWeb Server URL in your Dashboard, you should set SERVER_PATH to the value /servers/weweb-server. SERVER_PATH should end without a / .

Database configuration :

Varible nameRequiredDefault valueDescription
DB_HOSTNAMEYes-Database hostname
DB_PORTNo5432Database port
DB_NAMEYes-Database name
DB_USERNAMEYes-User name to connect to the Database
DB_PASSWORDYes-User password to connect to the Database
DB_SCHEMANopublicSchema to connect to the Database
DB_SSLNofalseUse SSL connection to database

AWS S3 configuration (not required if a different storage is used) :

Varible nameRequired
AWS_ACCESS_KEY_IDYes
AWS_SECRET_ACCESS_KEYYes
BUCKETREGIONYes
BUCKETNAMEYes

Publish a new version of a project

  1. Publish your project on WeWeb Dashboard and wait for it to finish
  2. Go to your project's Dashboard > Self-Hosting and download the project's ZIP archive
  3. Unzip the archive in your storage. We advise you to use subfolders for each projects and each versions of your projects to prevent downtime.
  4. Go to your project's Dashboard > Self-Hosting and click on Configure WeWeb Server

The new version of your project is now live !

Updating weweb-server

TBD

WeWeb Public API

WeWeb Public API allows you to automate deployements on your weweb-server.

WeWeb Public API has a rate limit of 3 calls per seconds and will return 429 Too many requests error if the limit is hit.

Access to WeWeb Public API

Please contact the WeWeb team to get access to WeWeb Public API.

Authentication

WeWeb Public API authentication is done using an Authorization header in every requests.

The value of this header should be Bearer <YOUR WORKSPACE PRIVATE KEY>.

You workspace Private Key can be found under the Settings tab in your workspace.

You can generate a new Private Key at any time but this will invalidate the old one.

Example : headers: {"Authorization": "Bearer WW-PRIVATE-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"}

Requests available :

Start the publication of a project

Check the publication status of a project

Download Raw project files ZIP (not built) by version

Start project file ZIP (built and ready for deployment) generation by version

Get project file ZIP (built and ready for deployment) generation status by version

Download project files ZIP (built and ready for deployment) by version

Download “weweb-server.config.json“ by version

Activate a version in you weweb-server

Typical auto deploy script

A typical auto deploy script should be :

 1. Start the publication of a project.
 2. Store the version provided by the previous request
 3. While the project is publishing, check the publication status of a project. The publication is done when the progress is 100 and status is "published".
 4. Start project file ZIP (built and ready for deployment) generation by version using the version provided in the start publication step
 5. While the ZIP file is being generated, get the generation status by version using the version provided in the start publication step
 6. Download project files ZIP by version using the version provided in the start publication step
 7. Save the downloaded ZIP file
 8. Extract the download zip file to your weweb-server storage at the right place (defined by FILES_PATH
 9. Activate the published version in you weweb-server using the version provided in the start publication step

Start the publication of a project

  • Method : POST
  • URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/publish:workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project
  • Data : env : accepts values production or staging and defines the target of the publication. Publishing to production will also publish to staging.
  • Returns :
{
	"progress": 0,    //Progress of the publish from 0 to 100
	"message": "Fetching data",    //Progress message
	"status": "publish",    //Status of the publish. Can be : publish / published / error
	"environment": "production",    //Target environment
	"version": 33,    //Version of current publish
	"createdAt": "2022-12-12T16:13:47.142Z"    //Date of creation
}

Check the publication status of a project

  • Method : GET
  • URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/publish/status:workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project
  • Data : no data.
  • Returns :
{
	"progress": 0,    //Progress of the publish from 0 to 100
	"message": "Fetching data",    //Progress message
	"status": "publish",    //Status of the publish. Can be : publish / published / error
	"environment": "production",    //Target environment
	"version": 33,    //Version of current publish
	"createdAt": "2022-12-12T16:13:47.142Z"    //Date of creation
}

Download Raw project files ZIP (not built) by version

  • Method : GET
  • URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/versions/{{:version}}/download/raw:workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project :version can be found in the Versions tab of the project or as a result of previous requests.
  • Data : no data.
  • Returns : a ZIP file containing the Raw project files.

Start project file ZIP (built and ready for deployment) generation by version

  • Method : GET
  • URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/versions/{{:version}}/download/generate:workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project :version can be found in the Versions tab of the project or as a result of previous requests.
  • Data : no data.
  • Returns :
{
	"progress": 0,    //Progress of the generation from 0 to 100
	"status": "IN_PROGRESS",    //Status of the generation. Can be : IN_PROGRESS / DONE / ERROR 
}

Get project file ZIP (built and ready for deployment) generation status by version

  • Method : GET
  • URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/versions/{{:version}}/download/status:workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project :version can be found in the Versions tab of the project or as a result of previous requests.
  • Data : no data.
  • Returns :
{
	"progress": 0,    //Progress of the generation from 0 to 100
	"status": "IN_PROGRESS",    //Status of the generation. Can be : IN_PROGRESS / DONE / ERROR 
}

Download project files ZIP (built and ready for deployment) by version

  • Method : GET
  • URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/versions/{{:version}}/download:workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project :version can be found in the Versions tab of the project or as a result of previous requests.
  • Data : no data.
  • Returns : a ZIP file containing the project files ready for deployment.

Download “weweb-server.config.json“ by version

  • Method : GET
  • URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/versions/{{:version}}/config:workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project :version can be found in the Versions tab of the project or as a result of previous requests.
  • Data : no data.
  • Returns : Returns a JSON containing all the data needed to configure the weweb-server.

The result of this requets should be saved in a weweb-server.config.json file that is at in the root folder of weweb-server. At the next start, weweb-server will look for this file and create a new version on it's database. This is only useful if your weweb-server cannot be reached on the internet by our servers.

Activate a version in you weweb-server

This request is done directly to your weweb-server

  • Method : POST
  • URL : https://<YOUR WEWEB-SERVER URL>/public/v1/projects/{{:projectId}}/versions/{{:version}}/active:projectId can be found in the URL of the project :version can be found in the Versions tab of the project or as a result of previous requests.
  • Data : env : accepts values production or staging and defines the target of the activation.
  • Returns :
{
	"success": true,    //Success, can be `true` or `false`
}
Last Updated:
Contributors: Joyce Kettering