"Server mode" : Using MARL as a publishing tool

April 6, 2025 · View on GitHub

Starting from version 2.3.2, MARL can be used in what is called "server mode", as opposed to the default "local mode".

Those two modes are mutually exclusive.

Local vs. Server

TL;DR

Local mode:

  • The default mode
  • The easiest to use
  • Completely private
  • May not work with very large archives
    (possible workaround: remove attachments from archive)

Server mode:

  • A bit more technical (web server required)
  • Requires a bit of setup
  • Allows to make your archive public
    ⚠️ privacy considerations: remove private posts from your archive first; a tool is provided, see below
  • Can also be used in a private way (local web server)
  • Will handle very large archives better than local mode

Lengthy explanation

Local mode is the default. It simply allows the user to explore the content of their archive in the privacy of their own device. In this mode, MARL will start by showing a welcome screen and invite the user to select their archive file, located in their local file system. Once they do so, MARL unpacks and displays the content of the selected file. Everything takes place strictly in the browser, and no data is sent anywhere.

In server mode, MARL will automatically load one or several specific archives located on a web server, as specified in its configuration (see below). Only the specified archive(s) will be loaded: the user will NOT be able to load their own archive via drag and drop or a file selection field. This allows you to use MARL as a publication tool, making your archive viewable by anybody on the web. Of course it can also be used on a local web server.

In server mode, MARL does not load the entire ZIP file in the browser: it starts by fetching only the four JSON files at the archive root. The media attachments (images, videos or sounds) are then fetched individually from the server, and only when MARL actually needs to display them to the user.

One limitation of local mode is that if your archive file is very large (e.g. several gigabytes), it may fail to load because it exceeds the browser cache capacity. One imperfect workaround is to delete the media_attachments folder from your archive (by repackaging it), in which case you will be able to explore your posts without any attachments. Another solution is to use server mode, which can be also done on a local web server. In this case your data remains private (you don't need to put it on a public server) and you should be able to explore your archive with all the media attachments.

Privacy considerations (⚠️ please read carefully ⚠️)

In server mode, MARL still operates in the same, browser-centric logic as in local mode: all data related to your profile, posts, bookmarks and likes is first loaded to the browser, which is then tasked with performing all the operations requested by the user (filtering posts, paging, search etc).

This means that anybody accessing MARL in server mode basically gains full access to your archive.
If you are not comfortable with that, you should not use it in this way (or at least not make it public).

What about private posts?

By default, outbox.json also contains your private posts. As this is not something that most users would want when making their archive public, the MARL project includes a script that will take your outbox file and generate a new file, removing all private posts in it.

⚠️ Please understand that this operation is not automatic. It is your responsibility to execute the script in order to remove your private posts from your archive prior to publishing it. In order to avoid any faux-pas, MARL operating in server mode will not fetch the outbox.json under its original name; instead it will look for a file named outbox-public.json. This is to (hopefully) avoid people publishing their archive without realizing that it can make their private posts public.

  • If you use the outbox-cleanup script, it will automatically generate the file with the correct name. Do not forget to delete the original outbox.json file from your archive folder when you put it online (MARL will not attempt to access it, but other people may try).
  • If you want all your posts (private included) to be published, simply rename your outbox file to outbox-public.json. No need to use the script.

What about bookmarks and likes?

If you do not want to publish your bookmarks and/or liked posts, simply remove the corresponding files from your archive (bookmarks.json or likes.json). MARL will still work without those files.

Enable server mode

To use MARL in server mode, you need to:

  1. Unpack your archive
    This is important: in server mode, MARL will not do the unpacking of the ZIP file; instead, it will fetch files from your archive individually. So they have to be unpacked beforehand.

  2. Remove your private posts from outbox.json (script available)
    You can find this script in the tools/outbox-cleanup folder of the MARL project. Please refer to the readme.md file in this folder for more information.

  3. Upload your unpacked archive on a web server

  4. Configure MARL to tell it where it can find your unpacked archive
    The configuration takes place in the js/config.js file of the dist folder (or whatever folder MARL is located in). It contains more information about how to use it. If this file is not present, please copy and rename it from js/config.default.js.

  5. Upload MARL on a web server

That's it! When it loads the configuration (step 4), MARL will automatically switch to server mode.

Change the default options

You can also change de default values for all the options found in the "Tools" panel in the app (e.g. number of posts per page, combine panels, simplify post display etc). This also takes place in the js/config.js file. Please refer to this file for more information.

Note that this only changes the default values for those options. Users will still be able to use the Tools panel to set different options for themselves if they wish.