Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

Production Setup

Once you are happy with the content and appearance of your design system documentation site, it’s time to build for production deployment. Start up the build process with the following command:

npm run dspublisher:build

After it finishes, you can find the build artifacts under the dspublisher/out directory.

The folder dspublisher/out/public contains the output of the build process, consisting of static content such as HTML, CSS, JavaScript, images, and other content necessary for viewing the documentation site in the browser. Hosting the static content is quite straightforward and can be done in multiple different ways.

For example, see the Serving Static Content documentation on serving static content on nginx.

If your design system documentation website has live examples with Java code, you also need to have the documentation project server itself running in the background and responding to requests coming from the client. The build artifact directory includes the file dspublisher/out/docs.jar which is the executable server side counterpart for the website project. You can start it up by running the following command:

java -jar docs.jar

By default, the server responds to requests on port 8080.

Now that the setup for hosting the static site content and having the documentation Java project running in the background is defined, you’ll also need to setup a reverse proxy to connect these two. Essentially, the server hosting the static site content should proxy any requests starting with /vaadin and /connect to the documentation project server:

  • ROOT/vaadin/* → docs:8080/vaadin

  • ROOT/connect/* → docs:8080/connect

You can configure your server to fallback to respond with the 404 page in case a non-existing page is requested. You can use the default 404/index.html file in the root of the static content directory (which you can customize with the articles/404.asciidoc file).

You can test the build output with the simplified hosting example using Docker, which you can find in the documentation project. After successfully finishing the build process and having the build artifacts in their default location, run the following command inside the dspublisher/deployment-example-docker directory:

docker-compose up

Open http://localhost:80 to view the built design system documentation website.

4ED4BF50-CF65-4C54-9434-BEAB4271F33F