Learn more about WeWeb Public API here

weweb-server

Prerequisite

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.io.

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 name	Required	Default	Values	Description
NODE_ENV	Yes	-	production	Must be set to production
FILES_PATH	Yes	-	-	Path of a frontend project's files in your storage. More information
PUBLIC_KEY	Yes	-	-	Can be found in WeWeb Dashboard > Workspace > Settings
PRIVATE_KEY	Yes	-	-	Can be found in WeWeb Dashboard > Workspace > Settings
PORT	No	80	-	Port where weweb-server should run
SERVER_PATH	No	-	-	Sub path for your server url. Not required if your server url is an IP or a domain name. More information
WW_LOG_LEVEL	No	trace	fatal, error, warn, info, debug, trace	Logs weweb-server should display
HIDE_VERSION	No	-	false, true	Hide 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.
MULTI_THREAD	No	-	false, true	If true, the weweb-server will use all available CPUs to launch multiple threads.

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 name	Required	Default value	Description
DB_HOSTNAME	Yes	-	Database hostname
DB_PORT	No	5432	Database port
DB_NAME	Yes	-	Database name
DB_USERNAME	Yes	-	User name to connect to the Database
DB_PASSWORD	Yes	-	User password to connect to the Database
DB_SCHEMA	No	public	Schema to connect to the Database
DB_SSL	No	false	Use SSL connection to database

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

Varible name	Required
AWS_ACCESS_KEY_ID	Yes
AWS_SECRET_ACCESS_KEY	Yes
BUCKETREGION	Yes
BUCKETNAME	Yes

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.

Currently, access to WeWeb Public API is also granted if you have access to the self-hosting feature.

Beaking changes in last update

Some breaking changes have been introduced in the latest version of the API.

Check the Breaking changes section to know more.

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>.

Your 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 deployment of a project

Check the deployment status of a project

Download Raw project files ZIP (not built) 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

List versions of a project in you weweb-server

Typical auto deploy script

A typical auto deploy script should be :

 1. Start the publication of a project with "builtZip" set to true.
 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".
 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 deployment of a project

• Method : POST

• URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/deploy :workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project

• Data :

  • env [REQUIRED] : accepts values production or staging and defines the target of the deployment. Deploying to production will also deploy to staging.
  • commit [OPTIONAL] : Sring that will be used as the commit info.
  • rawZip [OPTIONAL] : accepts values true or false and defines if the deployment generates a ZIP containing raw project files.
  • builtZip [OPTIONAL] : accepts values true or false and defines if the deployment generates a ZIP containing built project files.
  • githubEnabled [OPTIONAL] : accepts values true or false and defines if the deployment pushes raw project files to the configured Github repository.

• Returns :

{
	"message": "Fetching data",    //Progress message
	"status": "deploying",    //Status of the deployment. Can be : deploying / deployed / failed
	"version": 33,    //Version of current publish
	"createdAt": "2022-12-12T16:13:47.142Z"    //Date of creation
}

Check the deployment status of a project

• Method : GET
• URL : https://api.weweb.io/public/v1/workspaces/{{:workspaceId}}/projects/{{:projectId}}/deploy/last :workspaceId can be found in the URL of the workspace :projectId can be found in the URL of the project
• Data : no data.
• Returns :

{
	"message": "Fetching data",    //Progress message
	"status": "deploying",    //Status of the deployment. Can be : deploying / deployed / failed
	"environment": "production",    //Target environment
	"version": 33,    //Version of current publish
	"logs": "deploy logs",    //Full logs of the deployment
	"rawZip": true,    //rawZip option entered on deploy start
        "builtZip": true,    //builtZip option entered on deploy start
        "githubEnabled": false,    //githubEnabled option entered on deploy start
	"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.

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`
}

List versions of a project in you weweb-server

This request is done directly to your weweb-server

• Method : GET
• URL : https://<YOUR WEWEB-SERVER URL>/public/v1/project/{{:projectId}}/versions :projectId can be found in the URL of the project
• Returns :

{
	"success": true,          //Success, can be `true` or `false`
	"data": [
		{
			"version": 1,     //Version number
			"prod": true,     //Whether the version is active in production or not
			"staging": false  //Whether the version is active in staging or not
		}
	]
}

[DELETED] 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.

[DELETED] 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.

Breaking changes

The last version of the publication changed some configuration in the Public API

• The endpoint to start a publication has been updated and its parameters has been modified :
  • New parameter : builtZip - BOOLEAN - set to true if you need the publication to generate a zip with the built files.
  • New parameter : rawZip - BOOLEAN - set to true if you need the publication to generate a zip with the raw files.
  • New parameter : githubEnabled - BOOLEAN - set to true if you need the publication tu push the raw files to a connected Github repository.
  • Removed data from response : progress is not present anymore in the result of the publish endpoint.
• The endpoint to monitor a publication has been updated and it's return value has been modified :
  • Removed data from response : progress is not present anymore in the result of the publish endpoint.
    • To know when a publication is done you have to monitor status in the response. Its value should be deployed when the publication is done.
• The endpoint to generate the built ZIP has been deleted as it is no more useful.
• The endpoint to get the built ZIP generation has been deleted as it is no more useful.