Setup / Tips🔗
Starting Servers with
When developing, it's very convenient to use the revolver sbt plugin. Start the sbt console and then run:
This starts a REST server. Once this started up, type:
if also a joex component is required. Prefixing the commads with
results in recompile+restart once a source file is modified.
It is possible to start both in the root project:
Custom config file🔗
The sbt build is setup such that a file
dev.conf in the directory
local (at root of the source tree) is picked up as config file, if
it exists. So you can create a custom config file for development. For
example, a custom database for development may be setup this way:
#jdbcurl = "jdbc:h2:///home/dev/workspace/projects/docspell/local/docspell-demo.db;MODE=PostgreSQL;DATABASE_TO_LOWER=TRUE;AUTO_SERVER=TRUE" #jdbcurl = "jdbc:mariadb://localhost:3306/docspelldev"
The frontend code is in the sub-project
webapp. Running sbt's
compile task, compiles elm sources and creates the final CSS file.
restserver module is build by sbt, the
sub-project is built as well and the final files to deliver are
updated. So, when in sbt shell, "watch-compile" the project
~ restserver/compile), re-compiles elm-code on
change. However, it also re-creates the final css, which is a rather
To speed things up when only developing the frontend, a bash script is
project/dev-ui-build.sh. Start the
restserver/reStart task as described above. Then run this
script in the source root. It will watch elm files and the css file
and re-compiles only on change writing the resulting files in the
correct locations so they get picked up by the restserver.
Now you can edit elm files and the
index.css and then only refresh
the page. Elm compilation is very fast, it's difficult to reach the
refresh button before it is done compiling :). When editing the CSS,
it takes a little longer, but this is hardly necessary, thanks to
There is still a problem: the browser caches the js and css files by
default, so a page refresh is not enough, you need to clear the cache,
too. To avoid this annoyance, set a env variable
DOCSPELL_ENV to the
dev. Docspell then adds a response header, preventing the
browser to cache these files. This must be done, obviously, before
starting the restserver:
The http API is specified in the corresponding
component section is being used to generate code for the client
and the server, so that both are always in sync. However, the route
definitions are not checked against the server implementation.
Changes to the openapi files can be checked by running a sbt task:
restapi/openapiLint //and/or joexapi/openapiLint
These tasks must not show any errors (it is checked by the CI). The warnings should also be fixed.
/nix contains nix expressions to install docspell via
the nix package manager and to integrate it into NixOS.
Testing NixOS Modules🔗
The modules can be build by building the
together with some nixpkgs version. For example:
This will build all modules imported in
create a virtual machine containing the system. After that completes,
the system configuration can be found behind the
symlink. So it is possible to look at the generated systemd config for
And with some more commands (there probably is an easier way…) the config file can be checked:
| | | | | | | |
To see the module in action, the vm can be started (the first line sets more memory for the vm):
The CI and making a release is done via github actions. The workflow is roughly like this:
- each PR is only merged if the
sbt citask returns successfully. This is ensured by the
ci.ymlworkflow that triggers on each pull request
- each commit to the
masterbranch is also going through
sbt ciand then a prerelease is created. The tag
nightlyis used to point to the latest commit in
master. Note, that this is discouraged by git, but github doesn't allow to create a release without a tag. So this tag moves (and is not really a tag then…). After the prerelease is created, the docker images are built and pushed to docker hub into the docspell organization. The docker images are also tagged with
nightlyat docker hub. This is all done via the
- A stable release is started by pushing a tag with pattern
v*to github. This triggers the
release.ymlworkflow which builds the packages and creates a release in draft mode. The
sbt citask is not run, because it is meant to only release commits already in the
masterbranch. After this completes, the release notes need to be added manually and then the release must be published at github. This then triggers the
docker-images.ymlworkflow, which builds the corresponding docker images and pushes them to docker hub. The docker images are tagged with the exact version and the
latesttag is moved to the new images. Another manual step is to set the branch
current-docsto its new state and push it to github. This will trigger a build+publish of the website.
- Publishing the website happens automatically on each push to the
current-docs. Changes to the current website must be based on this branch.
Some notes: I wanted a 2/3 step process when doing a stable release, to be able to add release notes manually (I don't want this to be automated right now) and to do some testing with the packages before publishing the release. However, for the nightly releases, this doesn't matter - everything must be automated here obviously. I also wanted the docker images to be built from the exact same artifacts that have been released at github (in contrast to being built again).