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 fullkopia
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 simplifiedkopia
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 thedist/kopia-ui
subdirectory -
$ make website
- builds kopia.io website using Hugo. The output is stored insite/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
The following picture provides high-level overview of the build pipeline.
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.
When developing the UI, the most convenient way is to use two terminals. The first terminal runs kopia server
without the UI. The second one runs development server of React with hot-reload, so changes are immediately reflected in the browser.
In the first terminal do:
$ make install-noui && $HOME/go/bin/kopia server
In the second terminal do:
$ make -C htmlui dev
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.
To make sure HTML pages compile correctly use:
$ make -C htmlui build-html
To manually build the kopia
binary with the embedded HTML that was just generated in the previous step:
$ go install -tags embedhtml
or
$ make install
When compiling Go code without embedhtml
build tag, the embedded UI will be just a placeholder. This is equivalent to:
$ make install-noui
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 Windowsdist/kopia-ui/mac/KopiaUI.app
- on macOSdist/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.
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.