mirror of
https://github.com/TheAnachronism/docspell.git
synced 2024-11-13 02:31:10 +00:00
150 lines
4.4 KiB
Markdown
150 lines
4.4 KiB
Markdown
+++
|
|
title = "Tips & Setup"
|
|
weight = 20
|
|
+++
|
|
|
|
# Starting Servers with `reStart`
|
|
|
|
When developing, it's very convenient to use the [revolver sbt
|
|
plugin](https://github.com/spray/sbt-revolver). Start the sbt console
|
|
and then run:
|
|
|
|
```
|
|
sbt:docspell-root> restserver/reStart
|
|
```
|
|
|
|
This starts a REST server. Once this started up, type:
|
|
|
|
```
|
|
sbt:docspell-root> joex/reStart
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
sbt:docspell-root> reStart
|
|
```
|
|
|
|
|
|
# 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:
|
|
|
|
``` bash
|
|
#jdbcurl = "jdbc:h2:///home/dev/workspace/projects/docspell/local/docspell-demo.db;MODE=PostgreSQL;DATABASE_TO_LOWER=TRUE;AUTO_SERVER=TRUE"
|
|
jdbcurl = "jdbc:postgresql://localhost:5432/docspelldev"
|
|
#jdbcurl = "jdbc:mariadb://localhost:3306/docspelldev"
|
|
|
|
docspell.server {
|
|
backend {
|
|
jdbc {
|
|
url = ${jdbcurl}
|
|
user = "dev"
|
|
password = "dev"
|
|
}
|
|
}
|
|
}
|
|
|
|
docspell.joex {
|
|
jdbc {
|
|
url = ${jdbcurl}
|
|
user = "dev"
|
|
password = "dev"
|
|
}
|
|
scheduler {
|
|
pool-size = 1
|
|
}
|
|
}
|
|
```
|
|
|
|
# Developing Frontend
|
|
|
|
The frontend is a SPA written in [Elm](https://elm-lang.org). The UI
|
|
framework in use is [tailwind](https://tailwindcss.com).
|
|
|
|
The frontend code is in the sub-project `webapp`. Running sbt's
|
|
`compile` task, compiles elm sources and creates the final CSS file.
|
|
Whenever the `restserver` module is build by sbt, the `webapp`
|
|
sub-project is built as well and the final files to deliver are
|
|
updated. So, when in sbt shell, "watch-compile" the project
|
|
`restserver`, (via `~ restserver/compile`), re-compiles elm-code on
|
|
change. However, it also re-creates the final css, which is a rather
|
|
long task.
|
|
|
|
To speed things up when only developing the frontend, a bash script is
|
|
provided in `project/dev-ui-build.sh`. Start the `restserver` once,
|
|
using `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
|
|
tailwind.
|
|
|
|
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
|
|
value `dev`. Docspell then adds a response header, preventing the
|
|
browser to cache these files. This must be done, obviously, before
|
|
starting the restserver:
|
|
|
|
``` bash
|
|
$ export DOCSPELL_ENV=dev
|
|
$ sbt "restserver/reStart"
|
|
```
|
|
|
|
# Nix Expressions
|
|
|
|
The directory `/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 `configuration-test.nix` file
|
|
together with some nixpkgs version. For example:
|
|
|
|
``` bash
|
|
nixos-rebuild build-vm -I nixos-config=./configuration-test.nix \
|
|
-I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-19.09.tar.gz
|
|
```
|
|
|
|
This will build all modules imported in `configuration-test.nix` and
|
|
create a virtual machine containing the system. After that completes,
|
|
the system configuration can be found behind the `./result/system`
|
|
symlink. So it is possible to look at the generated systemd config for
|
|
example:
|
|
|
|
``` bash
|
|
cat result/system/etc/systemd/system/docspell-joex.service
|
|
```
|
|
|
|
And with some more commands (there probably is an easier way…) the
|
|
config file can be checked:
|
|
|
|
``` bash
|
|
cat result/system/etc/systemd/system/docspell-joex.service | grep ExecStart | cut -d'=' -f2 | xargs cat | tail -n1 | awk '{print $NF}'| sed 's/.$//' | xargs cat | jq
|
|
```
|
|
|
|
To see the module in action, the vm can be started (the first line
|
|
sets more memory for the vm):
|
|
|
|
``` bash
|
|
export QEMU_OPTS="-m 2048"
|
|
./result/bin/run-docspelltest-vm
|
|
```
|
|
|
|
|
|
# Background Info
|
|
|
|
There is a list of [ADRs](@/docs/dev/adr/_index.md) containing
|
|
internal/background info for various topics.
|