mirror of https://github.com/kopia/kopia.git synced 2026-03-26 18:11:45 -04:00

Files

Jarek Kowalski daacc6a8f4 htmlui: moved HTML UI to separate repository (#1600 )

The source code for htmlui is now in github.com/kopia/htmlui
GitHub Actions will drop compiled builds in github.com/kopia/htmluibuild
where they are now used as a go module dependency.

This greatly simplifies the build and improves the security,
because Kopia will be consuming pre-built htmlui.

This also means kopia can now installed with embedded UI using:
`go install github.com/kopia/kopia@latest`

2021-12-18 12:28:30 -08:00

4.5 KiB

Raw Blame History

Kopia Build Architecture

Kopia build pipeline is set up to generate the following artifacts:

Standalone kopia executable for all supported platforms, optionally with embedded graphical UI
KopiaUI - desktop app for all supported platforms: Windows, macOS, and Linux
The static content of kopia.io website

Kopia build is based on Makefile and provides the following main targets:

$ make install - builds full kopia command-line executable that also embeds graphical UI components that can be used in a browser. The output is stored in $HOME/go/bin/kopia
$ make install-noui - builds simplified kopia executable without embedded graphical UI. The output is stored in $HOME/go/bin/kopia
$ make goreleaser && make kopia-ui - builds desktop application based on Electron using Electron Builder The output is stored in the dist/kopia-ui subdirectory
$ make website - builds kopia.io website using Hugo. The output is stored in site/public and published to Github Pages from Travis CI on each build.

The project structure is also compatible with go get, so getting the latest Kopia command line tool (albeit without any UI functionality) is as simple as:

$ go get github.com/kopia/kopia

Build Pipeline Overview

The following picture provides high-level overview of the build pipeline.

HTML UI

THe HTML UI builds HTML-based user interface that is embedded in Kopia binary by using go:embed.

The UI is build using React and more specifically Create React App toolchain.

The source code for HTML UI is in https://github.com/kopia/htmlui and pre-built UI HTML is available as Golang module that can be imported from github.com/kopia/htmluibuilds

When developing the UI, the most convenient way is to use two terminals. The first terminal runs kopia server which exposes the API that the UI needs. The second one runs development server of React with hot-reload, so changes are immediately reflected in the browser.

In the first terminal do:

$ go run . server --insecure --without-password

In the second terminal, in the htmlui repository run:

$ npm run start

This will automatically open the browser with the UI page on http://localhost:3000. Changing any file under htmlui will cause the browser to hot-reload the change. In most cases, the changes to the kopia server don't even require reloading the browser.

Changes to htmlui need to be individually submitted to their own repository and after they get built and tagged, you need to update the go.mod dependency:

go get -u github.com/kopia/htmluibuild

KopiaUI App

KopiaUI is built using Electron and packaged as native binary using Electron Builder. The app is just a shell that invokes kopia server --ui and connects the browser to it, plus it provides native system tray integration. Kopia executable is embedded as a resource inside KopiaUI app, to simplify usage.

To build the app:

$ make kopia-ui

The generated app will be in:

dist/kopia-ui/win-unpacked on Windows
dist/kopia-ui/mac/KopiaUI.app - on macOS
dist/kopia-ui/linux-unpacked on Linux

When developing the app shell it is convenient to simply run Electron directly on the source code without building.

$ make -C app dev

NOTE: this also opens the browser window due to CRA development server, but it can be safely disregarded. Because KopiaUI configuration pages are built using CRA, they also benefit from hot-reload while developing this way.

Website

The kopia.io website is built using Hugo.

To build the website use:

$ make -C site build

This will auto-generate Markdown files with documentation for currently supported Kopia CLI subcommands and store them under site/content/docs/Reference/Command-Line and then generate the website which is stored in site/public.

To see the website in a browser it's more convenient to use:

$ make -C site server

This starts a server on http://localhost:1313 where the website can be browsed.