Home
The German Archaeological Institute’s (DAI) new take on a field research documentation system.
Combining features of GIS, photo management, and database management systems in a unique and integrating manner, Field aims at facilitating archaeological workflows by reducing the overhead of using multiple systems. Developed in-house by the DAI’s information technology department, it targets primarily the needs of the institute’s excavations, older ones as well as those to come. Yet, due to the nature of its adjustable data model and the fact it is open source software, any interested third party is free to reuse and adjust it to their needs.
The main application is currently Field Desktop, with Field Mobile as an upcoming alternative still in early development. For the time being, if you are a researcher interested in using Field, we would suggest to first have a look at Field Desktop.
While it is possible to run just one Field Desktop installation for your project on a single machine, the strength of Field is its capability for automatic database- and filesyncing between different Field Desktop installations.
For institutions that consider using Field, we would recommend setting up FieldHub as a central server that serves as a centralized syncing target for all your researchers.
You find some examples for syncing setups below.
Field Desktop is the main desktop (MacOS, Windows or Linux) application for collecting data.
You can install the latest version of Field Desktop by downloading it from the GitHub releases page. Choose the installer for your operating system.
See the application's internal manual.
FieldHub serves as a central synchronisation server for Field Desktop clients.
There are two aspects to syncing Field data:
- Image data
- Database data
Image data is held directly in filesystem, while the database syncing is handled by CouchDB (FieldHub) or PouchDB (Field Desktop). FieldHub serves as a simple reverse proxy to a CouchDB installation and implements the image data syncing.
If you are already running your own CouchDB, you can install FieldHub alongside by setting its environment variables accordingly (see below).
- Docker
- CouchDB installation
The Docker images are currently hosted in the Github Container Registry: https://github.com/dainst/idai-field/pkgs/container/field_hub.
Environment variables
- HOST, the host domain you will run the application from, for example "server.field.idai.world". (required)
- SECRET_KEY_BASE, see https://hexdocs.pm/phoenix/deployment.html#handling-of-your-application-secrets (required)
- COUCHDB_URL, base url to your CouchDB installation, for example "http://example.com:5984". (required)
- COUCHDB_ADMIN_NAME, admin username for the CouchDB (optional, required for FieldHub CLI scripts)
- COUCHDB_ADMIN_PASSWORD, admin password for the CouchDB (optional, required for FieldHub CLI scripts)
Volumes
The FieldHub application will save images at /files within the Docker container. If you want to make the images persistent, you should therefore mount a host volume accordingly and make sure the container user has read/write access.
See also the deployment example.
If you have an existing project in your Field Client, you also have to create an empty project with the same name as described below. When you first sync your Field Client to the server, the server database and images will get updated to the Field Client project state.
- If your CouchDB is a new installation and not initialized yet, you should run the corresponding CLI command
setup_couchdb_single_node(). - Create one or more projects. It is expected that each project and its user have the same name. The easiest way to create an empty project is running one of the CLI
create_project_with_default_user(..)commands. This will achieve 4 things:- Create an empty database with the given name
- Create a user with the same name and a password
- Add the user as a member of the newly created database
- Create the image file directories in the filesystem
Afterwards you should be able to use the credentials to sync your Field Client with the server.
The FieldHub.CLI module implements a range of CLI functions.
To call the CLI functions (from within your FieldHub docker container) use the pattern:
/app/bin/field_hub eval 'FieldHub.CLI.<function_name>("<string parameter>")'.
For example add a user by running:
/app/bin/field_hub eval 'FieldHub.CLI.create_user("simon_hohl", "very_secret_password")'
FieldHub.CLI.setup_couchdb_single_node()
Runs a basic single node setup for CouchDB, required only if your CouchDB has not been initialized at all.
FieldHub.CLI.create_project_with_default_user("<project_name>", "<user_password>")
Creates a project with name <project_name>, adds a user with name <project_name> and password <user_password>.
FieldHub.CLI.create_project_with_default_user("<project_name>")
Creates a project with name <project_name>, adds a user with name <project_name> and a random password (make sure to write it down).
FieldHub.CLI.set_password("<user_name>", "<user_password>")
Sets new password <user_password> for user with name <user_name>.
Here are some network topologies currently in use.
This setup does not require a FieldHub server installation. All researchers sync between their machines (laptops or desktop PCs) directly.
flowchart LR;
A[Researcher A] <--> B[Researcher B];
A[Researcher A] <--> C[Researcher C];
C[Researcher C] <--> D[Researcher D];
C[Researcher C] <--> E[Researcher E];
A[Researcher A] <--> E[Researcher E];
classDef default color:#fff
style A fill:#008B00
style B fill:#008B00
style C fill:#008B00
style D fill:#008B00
style E fill:#008B00
If your institution wants to collect all research data centrally, you may setup a FieldHub server instance and let all your researchers sync to it.
flowchart LR;
Hub[FieldHub Server] <--> A[Researcher A, Project A];
Hub[FieldHub Server] <--> B[Researcher B, Project A];
Hub[FieldHub Server] <--> C[Researcher C, Project B];
Hub[FieldHub Server] <--> D[Researcher D, Project B];
classDef default color:#fff
style Hub fill:#00008B
style A fill:#008B00
style B fill:#008B00
style C fill:#008B00
style D fill:#008B00
If bandwidth is a concern on excavation, you may also use a desktop PC or laptop on site running Field Desktop as a local 'pseudo server' to collect data and facilitate syncing to your institution's FieldHub server. This will reduce redundant upload/download bandwith usage compared to the topology variant above.
flowchart LR;
Pseudo[Pseudo Server] <--> Hub[FieldHub Server];
Pseudo[Pseudo Server] <--> A[Researcher A];
Pseudo[Pseudo Server] <--> B[Researcher B];
Pseudo[Pseudo Server] <--> C[Researcher C];
Pseudo[Pseudo Server] <--> D[Researcher D];
classDef default color:#fff
style Hub fill:#00008B
style Pseudo fill:#008B00
style A fill:#008B00
style B fill:#008B00
style C fill:#008B00
style D fill:#008B00
The topologies above can also be combined.
flowchart LR;
Pseudo[Pseudo Server, Project A] <--> Hub[FieldHub Server];
Pseudo[Pseudo Server, Project A] <--> A[Researcher A, Project A];
Pseudo[Pseudo Server, Project A] <--> B[Researcher B, Project A];
Hub[FieldHub Server] <--> C[Researcher C, Project B];
Hub[FieldHub Server] <--> D[Researcher D, Project B];
A[Researcher A, Project A] <--> E[Researcher E, Project A];
A[Researcher A, Project A] <--> F[Researcher F, Project A];
G[Researcher G, Project A] <--> Hub[FieldHub Server];
classDef default color:#fff
style Hub fill:#00008B
style Pseudo fill:#008B00
style A fill:#008B00
style B fill:#008B00
style C fill:#008B00
style D fill:#008B00
style E fill:#008B00
style F fill:#008B00
style G fill:#008B00
After field research documentation has been created using Field Desktop, there are several ways to process or publish your data.
- Export CSV/GeoJSON/Shapefiles from within the Field Desktop application.
- Access the underlying CouchDB (FieldHub) or PouchDB (Field Desktop) directly. CouchDB provides its own Rest API, but there also exist native libraries like sofa for R. An example sofa implementation by Lisa Steinmann can be found here.