mirror of
https://github.com/TheAnachronism/docspell.git
synced 2025-06-22 02:18:26 +00:00
Initial website
This commit is contained in:
Eike Kettner
324
website/site/content/docs/install/installing.md
Normal file
324
website/site/content/docs/install/installing.md
Normal file
@ -0,0 +1,324 @@
|
||||
+++
|
||||
title = "Installing"
|
||||
weight = 20
|
||||
+++
|
||||
|
||||
# Docker
|
||||
|
||||
There is a [docker-compose](https://docs.docker.com/compose/) setup
|
||||
available in the `/docker` folder. This setup is also taking care of
|
||||
all the necessary [prerequisites](@/docs/install/prereq.md) and
|
||||
creates a container to watch a directory for incoming files. It's only
|
||||
3 steps:
|
||||
|
||||
1. Clone the github repository
|
||||
```bash
|
||||
$ git clone https://github.com/eikek/docspell
|
||||
```
|
||||
2. Change into the `docker` directory:
|
||||
```bash
|
||||
$ cd docspell/docker
|
||||
```
|
||||
3. Run `docker-compose up`:
|
||||
|
||||
```bash
|
||||
$ export DOCSPELL_HEADER_VALUE="my-secret-123"
|
||||
$ docker-compose up
|
||||
```
|
||||
|
||||
The environment variable defines a secret that is shared between
|
||||
some containers. You can define whatever you like. Please see the
|
||||
[consumedir.sh](@/docs/tools/consumedir.md#docker) docs for
|
||||
additional info.
|
||||
4. Goto `http://localhost:7880`, signup and login. When signing up,
|
||||
you can choose the same name for collective and user. Then login
|
||||
with this name and the password.
|
||||
|
||||
5. (Optional) Create a folder `./docs/<collective-name>` (the name you
|
||||
chose for the collective at registration) and place files in there
|
||||
for importing them.
|
||||
|
||||
The directory contains a file `docspell.conf` that you can
|
||||
[modify](@/docs/configure/_index.md) as needed.
|
||||
|
||||
# Download, Unpack, Run
|
||||
|
||||
You can install via zip or deb archives. Please see the
|
||||
[prerequisites](@/docs/install/prereq.md) first.
|
||||
|
||||
## Using zip files
|
||||
|
||||
You need to download the two files:
|
||||
|
||||
- [docspell-restserver-{{version()}}.zip](https://github.com/eikek/docspell/releases/download/v{{version()}}/docspell-restserver-{{version()}}.zip)
|
||||
- [docspell-joex-{{version()}}.zip](https://github.com/eikek/docspell/releases/download/v{{version()}}/docspell-joex-{{version()}}.zip)
|
||||
|
||||
|
||||
1. Unzip both files:
|
||||
``` bash
|
||||
$ unzip docspell-*.zip
|
||||
```
|
||||
2. Open two terminal windows and navigate to the the directory
|
||||
containing the zip files.
|
||||
3. Start both components executing:
|
||||
``` bash
|
||||
$ ./docspell-restserver*/bin/docspell-restserver
|
||||
```
|
||||
in one terminal and
|
||||
``` bash
|
||||
$ ./docspell-joex*/bin/docspell-joex
|
||||
```
|
||||
in the other.
|
||||
4. Point your browser to: <http://localhost:7880/app>
|
||||
5. Register a new account, sign in and try it.
|
||||
|
||||
Note, that this setup doesn't include watching a directory. You can
|
||||
use the [consumedir.sh](@/docs/tools/consumedir.md) tool for this or
|
||||
use the docker variant below.
|
||||
|
||||
## Using deb files
|
||||
|
||||
The DEB packages can be installed on Debian, or Debian based Distros:
|
||||
|
||||
``` bash
|
||||
$ sudo dpkg -i docspell*.deb
|
||||
```
|
||||
|
||||
Then the start scripts are in your `$PATH`. Run `docspell-restserver`
|
||||
or `docspell-joex` from a terminal window.
|
||||
|
||||
The packages come with a systemd unit file that will be installed to
|
||||
autostart the services.
|
||||
|
||||
# Nix
|
||||
|
||||
## Install via Nix
|
||||
|
||||
Docspell can be installed via the [nix](https://nixos.org/nix) package
|
||||
manager, which is available for Linux and OSX. Docspell is currently not
|
||||
part of the [nixpkgs collection](https://nixos.org/nixpkgs/), but you
|
||||
can use the derivation from this repository. This is sometimes
|
||||
referred to as [import from
|
||||
derivation](https://nixos.wiki/wiki/Import_From_Derivation).
|
||||
|
||||
For example, the `builtins.fetchTarball` function can be used to
|
||||
retrieve the files; then import the `release.nix` file:
|
||||
|
||||
``` nix
|
||||
let
|
||||
docspellsrc = builtins.fetchTarball "https://github.com/eikek/docspell/archive/master.tar.gz";
|
||||
in
|
||||
import "${docspellsrc}/nix/release.nix";
|
||||
```
|
||||
|
||||
This creates a set containing a function for creating a derivation for
|
||||
docspell. This then needs to be called like other custom packages. For
|
||||
example, in your `~/.nixpkgs/config.nix` you could write this:
|
||||
|
||||
``` nix
|
||||
let
|
||||
docspellsrc = builtins.fetchTarball "https://github.com/eikek/docspell/archive/master.tar.gz";
|
||||
docspell = import "${docspellsrc}/nix/release.nix";
|
||||
in
|
||||
{ packageOverrides = pkgs:
|
||||
let
|
||||
callPackage = pkgs.lib.callPackageWith(custom // pkgs);
|
||||
custom = {
|
||||
docspell = callPackage docspell.currentPkg {};
|
||||
};
|
||||
in custom;
|
||||
}
|
||||
```
|
||||
|
||||
The `docspell` custom package is again a set that contains derivations
|
||||
for all 3 installable docspell programs: the restserver, joex and the
|
||||
tools.
|
||||
|
||||
Then you can install docspell via `nix-shell` or `nix-env`, for example:
|
||||
|
||||
``` bash
|
||||
$ nix-env -iA nixpkgs.docspell.server nixpkgs.docspell.joex nixpkgs.docspell.tools
|
||||
```
|
||||
|
||||
You may need to replace `nixpkgs` with `nixos` when you're on NixOS.
|
||||
|
||||
The expression `docspell.currentPkg` refers to the most current
|
||||
release of Docspell. So even if you use the tarball of the current
|
||||
master branch, the `release.nix` file only contains derivations for
|
||||
releases. The expression `docspell.currentPkg` is a shortcut for
|
||||
selecting the most current release. For example it translates to
|
||||
`docspell.pkg docspell.cfg.v{{ pversion() }}` – if the current version
|
||||
is `{{version()}}`.
|
||||
|
||||
|
||||
## Docspell on NixOS {#nixos}
|
||||
|
||||
If you are running [NixOS](https://nixos.org), there is a module
|
||||
definition for installing Docspell as a service using systemd.
|
||||
|
||||
There are the following modules provided:
|
||||
|
||||
- restserver
|
||||
- joex
|
||||
- consumedir
|
||||
|
||||
The `consumedir` module defines a systemd unit that starts the
|
||||
`consumedir.sh` script to watch one or more directories for new files.
|
||||
|
||||
You need to import the `release.nix` file as described above in your
|
||||
`configuration.nix` and then append the docspell module to your list of
|
||||
modules. Here is an example:
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
let
|
||||
docspellsrc = builtins.fetchTarball "https://github.com/eikek/docspell/archive/master.tar.gz";
|
||||
docspell = import "${docspellsrc}/nix/release.nix";
|
||||
in
|
||||
{
|
||||
imports = [ mymodule1 mymodule2 ] ++ docspell.modules;
|
||||
|
||||
nixpkgs = {
|
||||
config = {
|
||||
packageOverrides = pkgs:
|
||||
let
|
||||
callPackage = pkgs.lib.callPackageWith(custom // pkgs);
|
||||
custom = {
|
||||
docspell = callPackage docspell.currentPkg {};
|
||||
};
|
||||
in custom;
|
||||
};
|
||||
};
|
||||
|
||||
services.docspell-restserver = {
|
||||
enable = true;
|
||||
base-url = "http://docspelltest:7880";
|
||||
# ... more settings here
|
||||
};
|
||||
services.docspell-joex = {
|
||||
enable = true;
|
||||
base-url = "http://docspelltexst:7878";
|
||||
# ... more settings here
|
||||
};
|
||||
services.docspell-consumedir = {
|
||||
enable = true;
|
||||
watchDirs = ["/tmp/test"];
|
||||
urls = ["http://localhost:7880/api/v1/open/upload/item/the-source-id"];
|
||||
};
|
||||
|
||||
...
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Please see the `nix/module-server.nix` and `nix/module-joex.nix` files
|
||||
for the set of options. The nixos options are modelled after the
|
||||
default configuration file.
|
||||
|
||||
The modules files are only applicable to the newest version of
|
||||
Docspell. If you really need an older version, checkout the
|
||||
appropriate commit.
|
||||
|
||||
## NixOS Example
|
||||
|
||||
This is a example system configuration that installs docspell with a
|
||||
postgres database. This snippet can be used to create a vm (using
|
||||
`nixos-rebuild build-vm` as shown above) or a container, for example.
|
||||
|
||||
``` nix
|
||||
{ config, pkgs, ... }:
|
||||
let
|
||||
docspellsrc = builtins.fetchTarball "https://github.com/eikek/docspell/archive/master.tar.gz";
|
||||
docspell = import "${docspellsrc}/nix/release.nix";
|
||||
in
|
||||
{
|
||||
imports = docspell.modules;
|
||||
|
||||
nixpkgs = {
|
||||
config = {
|
||||
packageOverrides = pkgs:
|
||||
let
|
||||
callPackage = pkgs.lib.callPackageWith(custom // pkgs);
|
||||
custom = {
|
||||
docspell = callPackage docspell.currentPkg {};
|
||||
};
|
||||
in custom;
|
||||
};
|
||||
};
|
||||
|
||||
##### just for the example…
|
||||
users.users.root = {
|
||||
password = "root";
|
||||
};
|
||||
#####
|
||||
|
||||
# install docspell-joex and enable the systemd service
|
||||
services.docspell-joex = {
|
||||
enable = true;
|
||||
base-url = "http://localhost:7878";
|
||||
bind = {
|
||||
address = "0.0.0.0";
|
||||
port = 7878;
|
||||
};
|
||||
scheduler = {
|
||||
pool-size = 1;
|
||||
};
|
||||
jdbc = {
|
||||
url = "jdbc:postgresql://localhost:5432/docspell";
|
||||
user = "docspell";
|
||||
password = "docspell";
|
||||
};
|
||||
};
|
||||
|
||||
# install docspell-restserver and enable the systemd service
|
||||
services.docspell-restserver = {
|
||||
enable = true;
|
||||
base-url = "http://localhost:7880";
|
||||
bind = {
|
||||
address = "0.0.0.0";
|
||||
port = 7880;
|
||||
};
|
||||
auth = {
|
||||
server-secret = "b64:EirgaudMyNvWg4TvxVGxTu-fgtrto4ETz--Hk9Pv2o4=";
|
||||
};
|
||||
backend = {
|
||||
signup = {
|
||||
mode = "invite";
|
||||
new-invite-password = "dsinvite2";
|
||||
invite-time = "30 days";
|
||||
};
|
||||
jdbc = {
|
||||
url = "jdbc:postgresql://localhost:5432/docspell";
|
||||
user = "docspell";
|
||||
password = "docspell";
|
||||
};
|
||||
};
|
||||
};
|
||||
|
||||
# install postgresql and initially create user/database
|
||||
services.postgresql =
|
||||
let
|
||||
pginit = pkgs.writeText "pginit.sql" ''
|
||||
CREATE USER docspell WITH PASSWORD 'docspell' LOGIN CREATEDB;
|
||||
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO docspell;
|
||||
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO docspell;
|
||||
CREATE DATABASE DOCSPELL OWNER 'docspell';
|
||||
'';
|
||||
in {
|
||||
enable = true;
|
||||
package = pkgs.postgresql_11;
|
||||
enableTCPIP = true;
|
||||
initialScript = pginit;
|
||||
port = 5432;
|
||||
authentication = ''
|
||||
host all all 0.0.0.0/0 md5
|
||||
'';
|
||||
};
|
||||
|
||||
|
||||
networking = {
|
||||
hostName = "docspellexample";
|
||||
firewall.allowedTCPPorts = [7880];
|
||||
};
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user