do•doc (or dodoc) is a free and open-source documentation tool, initially designed for use in classrooms with children. It enables one to capture traces from an on-going experience for later reflections, reconstructions and creation of narratives. A physical device can be associated with the software to simplify usage, especially with young people. Two versions are available: the local app that can be installed for offline use, and the online webapp that can be accessed from any device connected to the Internet.
do•doc is created by a variety of people: pupils, teachers, trainers, makers, artists, etc. Anyone is welcome to contribute to its development, on Github or via the forum (contributions can be in English or French): https://forum.latelier-des-chercheurs.fr/
do•doc was initially created by l'Atelier des chercheurs (Sarah Garcin, Pauline Gourlet & Louis Eveillard).
More information:
- in English: https://latelier-des-chercheurs.fr/en/tools/dodoc
- en Français : https://latelier-des-chercheurs.fr/outils/dodoc
And on the forum (mainly in French but you can post in English):
https://forum.latelier-des-chercheurs.fr/
do•doc is free and open source. The code is licensed under AGPLv3, and the graphic assets (icons, pictograms, user interface) are under a CC-BY-SA license.
The font Luciole is licensed under the Creative Commons Attribution 4.0 and embedded with permission from Laurent Bourcellier and Jonathan Fabreguettes. The font Belle Allure is used with permission from Jean Boyault.
-
main --> default branch, latest stable version. Unified branch supporting both Electron (offline app) and Node (server) modes. See release page for Linux/Mac/Windows installers.
-
main-dev --> fixes and small improvements on top of the current version. Used for testing before merging changes to main.
-
next --> code for the next major version. Unified branch supporting both Electron and Node modes. Use at your own risks.
npm install sharp@0.31.3
Note 2: bufferutil seems to be necessary specifically for intel macOS.
Download the latest release from the release page.
macOS ships two signed DMGs — use the one that matches your Mac:
| File | For |
|---|---|
dodoc-*-macos-arm.dmg |
Apple Silicon (M1, M2, M3, M4, …) |
dodoc-*-macos-intel.dmg |
Intel Macs (x86_64, typically sold before late 2020) |
Not sure which you have? Apple menu → About This Mac: a Chip line means Apple Silicon (arm); a Processor line (e.g. “Intel Core i5”) means Intel. Apple Silicon Macs can run the Intel build via Rosetta, but the ARM build is native and recommended. Intel Macs cannot run the ARM build.
See https://forum.latelier-des-chercheurs.fr/t/installer-do-doc-en-mode-developpement/426
To install do•doc in dev mode, you need to have Node.js and npm installed. Clone this repository and follow the instructions below based on your use case.
For running do•doc on a server with Puppeteer (for PDF/screenshot generation):
npm install
npm startOptional — Poppler (pdftoppm): For faster PDF thumbnail generation on the server, install Poppler so the pdftoppm binary is on your PATH (it is not an npm package). If Poppler is not installed, do•doc falls back to the existing web preview path (Puppeteer). Examples: macOS — brew install poppler; Debian/Ubuntu — apt install poppler-utils.
Available scripts for Node mode:
npm start- run the app with minimal loggingnpm run debug- run the app with debug logging
For running do•doc as a desktop application with Electron:
npm install
cd electron
npm install
npm startNote: When building Electron app, electron-builder automatically excludes puppeteer, typescript, and platform-folders from the final package to reduce app size. Both modes work from the same dependencies.
Available scripts for Electron mode (run from /electron folder):
npm start- run the Electron app with minimal loggingnpm run debug- run the app to debug locallynpm run debug-lr- run the app in debug mode with live reloadnpm run pack- package the app (without creating installer)npm run dist- build distributable installers
For development with live reload (client-side code):
You need to open a second terminal to run the vite/livereload server:
cd client
npm i
npm run devBecause of recent security changes on Ubuntu, you may encounter the following error on npm start or debug:
[44615:1003/212648.080818:FATAL:sandbox/linux/suid/client/setuid_sandbox_host.cc:169] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /home/julien/dodoc12/dodoc/electron/node_modules/electron/dist/chrome-sandbox is owned by root and has mode 4755.
To fix, use the following commands:
cd electron/node_modules/electron/dist/
sudo chown root chrome-sandbox
chmod 4755 chrome-sandboxHTTPS is required for WebSockets, camera/geolocation APIs, and other secure-context features. The backend uses self-signed certs by default, which browsers reject. Use mkcert for locally-trusted certificates:
# Install mkcert (macOS)
brew install mkcert
mkcert -install # trust the local CA, run once
# Generate certs and update settings.json
npm run setup-httpsRestart the server and open https://localhost:8080 — the browser will trust the certificate.
This method makes the installation of do•doc a bit simpler.
You need to have docker installed on your machine.
Run docker compose up -d, wait for it to initialize completely, and visit https://localhost:8080.
Your data is persistent (in ./dodoc-data directory).
If you prefer to customise the container, the basic pattern for starting a do•doc instance is:
$ docker run --name my-dodoc -p 8080:8080 -v ./dodoc-data:/home/node/Documents -d ghcr.io/l-atelier-des-chercheurs/dodoc:latest
Your data is persistent (in ./dodoc-data directory).
Then, access it via https://localhost:8080.
When starting the app for the first time, a message will tell you about an admin account that is created by default. Its password is "dodoc". Connect to this account and change the password by opening that account's page and clicking Options, and editing the password field. It is recommended to open the admin settings afterwards (the gear icon in the top bar) and read/adapt all settings.
More advanced settings are available to all by duplicating the settings.example.json file and renaming it to settings.json. You can override the default settings_base.json values with ones you need:
-
set the url where dodoc will be accessed (used for emails sent to users) (for example, https://test.dodoc.fr)
-
adapt the port used on startup, useful when hosting multiple dodoc on the same server (possible values: any port not already used, for example 443 or 8000)
-
indicate a bonjour domain for local discovery, like dodoc.local
-
change the folder used for storing all the user-generated contents by editing the contentPath field.
- if the value is just a string without any slashes (like "dodoc"), then this will be the name of the folder used in the /Documents subfolder.
- if the value contains any forward slashes (/) or system path separators, it will be treated as a full path (like /mnt/storage/dodoc-custom)
- if the specified path is not writable, do•doc will automatically fall back to using a "dodoc" folder in the Documents directory
-
if you'd like for dodoc to be able to send email to help users recover their password, fill in the information to a mail server and account with the "mailer" property.
Everything is structured in folders/files, so as to mirror the content in the filesystem. No database is used, almost all the content are saved in the content folder (by default /Documents/dodoc_next).
Folders contain a meta.txt file and media files (images, videos, audios, 3D/stl, texts, or any other kind of files).
Default values are:
- $admins (Array, editable) list of admins paths
- $contributors (Array, editable) list of contributors paths
- $cover (Object, editable) if a meta_cover.jpeg is present in the root of the folder
- $preview (String, editable) if set, search for a meta filename in this folder and read it when reading folder (useful for advanced cover of this folder)
- $date_created (Date) when the folder was created
- $date_modified (Date) when the folder was last edited
- $files_count (Number) number of files in that folder
- $folders_count (Number) total count of content folders across all subfolder types (e.g., for a space: number of projects; for a project: total of publications + makes + stopmotions)
- $date_last_file (Date) when the last file was uploaded
- $files (Array) list of all the files in this folder (see Files below) (bypass with no_files=true to improve performance where files are not needed)
- $status (String, editable) determines whether the folder gets listed
- $public (Boolean, editable) if true, return that folder, its files, and its source medias even when request is not auth
- $password (String, editable, stored as hash) limit editing to users with password
- $path (String) path to folder, matches filesystem structure and URL
- $infos (Object) data gathered from the folder itself (only available when url is appended with ?detailed=true)
- size (Number) size in bytes
Custom values can be defined in the schema property in settings_base.json. Editable default values and all custom values can only be edited by an $admin.
Each file has default values and custom values as well. Default values are:
- $admins (Array, editable) list of admins paths (will be used to set file permissions in the future)
- $contributors (Array, editable) list of contributors paths (will be used to set file permissions in the future)
- $authors (Array, editable) list of authors paths (information only, not actually used server-side)
- $path (String) path to meta text file, matches filesystem structure and URL
- $date_created (Date) when the file was created
- $date_uploaded (Date) when the file was uploaded
- $date_modified (Date) when the file was last edited
- $media_filename (String, editable) name of the file
- $type (String, editable) type of media file among the following: _image, video, audio, stl, text, pdf, other_
- $status (String, editable) determines whether the file gets listed when getFiles is called by non-authors
- $origin (String, editable) used to indicate the origin of the media (capture page, upload, etc.)
- $processing (Array, editable) used to list processing applied to media (blurred, cropped, resized, etc.)
- $thumbs (object) list of possible media image thumbs
- $content (String, editable) text content of a file
- $credits (String, editable) Credits for media
- $location (Object, editable) GPS location for file
- $infos (object) data gathered from the file itself
- mtimems (Date) last modified time for media file
- duration (Number) for videos and audios
- width (Number) for images and videos
- height (Number) for images and videos
- ratio (Number) for images and videos
- size (Number) size in bytes
- gps (Object)
- hash (String) file hash (to find duplicates)
Custom values can be defined in the schema property in settings_base.json. Editable default values and all custom values can only be edited by an $admins.
When you first open do•doc in your browser, you may see a security warning about the SSL certificate. This is normal and expected because do•doc uses a self-signed certificate for local HTTPS connections.
To proceed safely:
- Click "Advanced" or "Show Details" in your browser
- Click "Proceed to localhost (unsafe)" or "Accept the risk and continue"
- The warning will not appear again for this session
This warning appears because the certificate is self-signed (not issued by a trusted certificate authority), but it's completely safe for local use. The certificate is included with the application and is only used for local connections.
Each folder and each file have a "$status" property, which defines who can read them using getFolders, getFolder, getFiles and getFile:
- by default, it is set to private: folder will only be listed by their respective authors and instance admins.
- otherwise, if set to anything else, they will be listed by anyone (loggedin or not, as long as they have access to dodoc)
If a folder has a $password, then this ressource and its content can only be edited by people that are logged in to this folder using its password.
If a folder has $admins, only people logged in with a token that matches one of these $admin path can edit/remove this folder's meta and its subfolders.
If a folder has $contributors, people logged in with a token that matches one of these $contributors can not edit this folder's meta but can create/edit/remove subfolders or import/edit/remove files.
If a folder has $contributors = "everyone", all users (including anonymous, non logged-in users) have contributors' permissions.
If a folder has $admins = "everyone", all users (including anonymous) have admins' permissions.
If a folder has $admins = "parent_contributors" then all parent's $contributors are admins to this folder. This is the same behaviour as files in that parent folder.
If a folder has $admins = "authors" then all logged in authors are admins to this folder (anonymous contributions are forbidden).
These permissions trickle down: an instance admin has admin rights to all the instance contents. A space admin has admin rights to all its projects. A project admin has admin rights to all its content (medias, stopmotions, publications).
An instance contributor, though, only has contributors rights to the direct content it contains. For instance, a contributor to a space can create a project, but not remove a project he/she is not an $admin of.
If a folder type schema has the property $can_be_created_by: "everyone", this overrides the above behaviour and such folder can be created by all users even those that are not logged in. This is useful for accounts creation.
If a folder has $can_be_remixed = true, it can be remixed: duplicated somewhere else to the same level. When it is remixed, the path to the new folder gets appended to the array $list_of_remixes and the remix folder gets a $is_remix_of string.
The path to a ressource is decomposed like this:
/type-of-ressource/name-of-ressource/type-of-child-ressource/name-of-child-ressource
For example, with the following schema:
{
"schema": {
"$folders": {
"spaces": {
"$cover": {
"width": 1200,
"height": 1200,
"thumbs": {
"resolutions": [50, 320, 640, 1200]
}
},
"fields": {
"title": {
"type": "string"
}
},
"$folders": {
"projects": {
"$cover": {
"width": 2000,
"height": 2000,
"thumbs": {
"resolutions": [50, 320, 640, 2000]
}
},
"fields": {
"title": {
"type": "string",
"unique": true
}
},
"$folders": {
"publications": {
"$cover": {
"width": 1200,
"height": 1200,
"thumbs": {
"resolutions": [50, 320, 640, 1200]
}
},
"fields": {
"title": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
Then the following routes will redirect to:
-
/spaces --> returns a list of all folders in /spaces with their metas
-
/spaces/bonjour --> returns the meta of a single "bonjour" folder with a list of all their files with their metas
-
/spaces/bonjour/projects --> returns a list of all folders in /spaces/bonjour/projects with their metas
-
/spaces/bonjour/projects/elephant-with-plywood --> returns the meta of a single "elephant-with-plywood" folder with a list of all their files with their metas
-
/spaces/bonjour/projects/elephant-with-plywood.zip --> downloads a zip file with all the content of that folder
-
/spaces.zip --> downloads a zip of the
spacesdirectory under your content folder as-is: slug folders, dotfiles such as.slug-sequence.json,_bin, etc.—same hierarchy as on disk. -
/spaces/bonjour/projects.zip --> same for projects under that space (
/spaces/bonjour/projects/). -
/spaces/bonjour/projects/elephant-with-plywood/publications.zip --> deepest type step in this example schema (
publicationsunder that project folder).
Actual HTTP routes use the /_api2/... prefix (e.g. /_api2/spaces/bonjour/projects.zip). Folder-type archives require local admin rights like the usual Download permission for .zip; for a root type like _api2/projects.zip (schema-dependent), ACL falls back on instance admins (path "."). The journal logs download_folder_type for those requests.
For an existing folder:
Role | Edit | Upload file | Create subfolder | Export | Copy | Download | GeneratePreview |
-------------------------------------------------------------------------------------------------------------
Instance admins | x | x | x | x | x | x | x |
Folder $admins | x | x | x | x | x | x | x |
Folder $contributors | | x | x | | | | |
-------------------------------------------------------------------------------------------------------------
So, for example for a space /bonjour, its $admins can edit all meta properties while a contributor can only import/edit/remove files, and create projects (of which they'll be $admins by default).
Data stored in the LocalStorage (similar to cookies) :
- sessionID: random identifier to persist connection
- general_password: access password for dodoc if set for that instance, and if "remember" is checked
- tokenpath: login identifier, to reconnect to a logged in account when the page is refreshed
- selected_devices: selected video/audio devices in Capture page
- location_to_add_to_medias: coordinates picked to add to captured media
- fontLastUsed: last font used in a text block
- language: lang picked by user if it was changed from the default (browser or OS langage)
- translations_to_share: when using the translation helper, translations entered by a user
- show_meta_sidebar: show/hide the information sidebar when opening the modal for a media in Collect
- library_tile_mode: last used media preview mode in Collect
- page_settings: for each publication, remember grid options (show/hide, snap, gridstep)
All API calls (getting content, creating folders, etc.) are logged in a "journal" folder, in the content folder. Each run of the app is stored in a JSONL file named with the timestamp it was created. Each line in this file logs the timestamp, the user who requested it, from what kind of device, the ip address, and if the call was successull or not.
Only instance admins can load logging files from the app.
These logs contain both general app-related events (like which version of node.js is running, is there any settings.json environment specific files) and specific content related.