Configuring a File Base

ENiGMA½ offers a powerful and flexible file base. Configuration of file the file base and areas is handled via the fileBase section of config.hjson.

ENiGMA½ File Base Key Concepts

First, there are some core concepts you should understand:

Storage Tags
Area Tags

Storage Tags

Storage Tags define paths to physical (filesystem) storage locations that are referenced in a file Area entry. Each entry may be either a fully qualified path or a relative path. Relative paths are relative to the value set by the fileBase.areaStoragePrefix key (defaults to /path/to/enigma-bbs/file_base).

Below is an example defining some storage tags using the relative and fully qualified forms:

storageTags: {
  retro_pc_dos: "dos" // relative
  retro_pc_bbs: "pc/bbs" // still relative!
  bbs_stuff: "/path/to/bbs_stuff_storage" // fully qualified
}

Wildcard (Recursive) Storage Tags

Appending /* to a storage tag path marks it as wildcard — the scanner will recursively walk all subdirectories under the base path rather than only looking at files in the root of the tag directory. This is useful for organically-structured collections where files live in year, month, or category subdirectories.

storageTags: {
    scene_files: "/path/to/scene/*"   // recursive — scans all subdirs
    flat_files:  "/path/to/flat"      // flat — root directory only
}

ENiGMA½ tracks which subdirectory each file came from (relPath) so that files in different subdirectories with the same filename are treated as distinct entries. The relPath is stored relative to the tag’s base directory (e.g. 2024/April).

When an area mixes flat and wildcard tags, flat tags are always scanned first. Any subdirectories that are explicitly covered by a flat tag are automatically excluded from the wildcard scan to prevent double-indexing.

.enigmaignore files — place a .enigmaignore file anywhere inside a wildcard tag’s tree to exclude matching files or directories from scanning. Patterns follow gitignore syntax and are applied relative to the directory containing the .enigmaignore.

Areas

File base Areas are configured using the fileBase.areas configuration block in config.hjson. Each entry’s block starts with an area tag. Valid members for an area are as follows:

Item	Required	Description
`name`	Yes	Friendly area name.
`desc`	No	Friendly area description.
`storageTags`	Yes	An array of storage tags for physical storage backing of the files in this area. If uploads are enabled for this area, first storage tag location is utilized!
`sort`	No	If present, provides the sort key for ordering. `name` is used otherwise.
`hashTags`	No	Set to an array of strings or comma separated list to provide default hash tags for this area.

Example areas section:

areas: {
  retro_pc: { // an area tag!
    name: Retro PC
    desc: Oldschool PC/DOS
    storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
    hashTags: ["retro", "pc", "dos" ]
  }
}

The above example defines an area called “Retro PC” which is referenced via the area tag of retro_pc. Two storage tags are used: retro_pc_dos, and retro_pc_bbs. These storage tags can be seen in the Storage Tags example above.

Example Configuration

This combines the two concepts described above. When viewing the file areas from ENiGMA½ a user will only see the “Retro PC” area, but the files in the area are stored in the two locations defined in the storageTags section. We also show a uploads area. Uploads are allowed due to the ACS block. See Access & Uploads for more information.

Storage does not have to be local: see Network Mounts & Symlinks for serving areas from a NAS or another machine.

fileBase: {
  // override the default relative location
  areaStoragePrefix: /enigma-bbs/file_base

  storageTags: {
    retro_pc_dos: "dos"
    retro_pc_bbs: "pc/bbs"
    scene_files:  "/path/to/scene/*"  // wildcard — scans subdirs recursively
  }

  areas: {
    retro_pc: {
      name: Retro PC
      desc: Oldschool PC/DOS
      storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
    }

    scene: {
      name: Scene Files
      desc: Scene releases organized by year/month
      storageTags: [ "scene_files" ]
    }

    uploads: {
      name: Uploads
      desc: User uploads
      acs: {
        // allow any user to upload here
        write: GM[users]
      }
      storageTags: [ "user_uploads" ]
    }
  }
}

Importing Areas

Areas can also be imported using oputil using proper FileGate “RAID” aka FILEBONE.NA style files. After importing areas, you may wish to tweak configuration such as better desc fields, ACS, or sorting.

Importing Files (Scan For New Files)

A common task is to import existing files to area(s). Consider a collection of retro BBS files in the area “Retro PC” (tag: retro_pc above) under the storage tag of retro_pc_bbs. You might choose to scan for new files in this area (and thus import new entries) as follows with oputil’s fb scan:

./oputil.js fb scan --quick --tags retro,bbs,pc retro_pc@retro_pc_bbs

Here we have asked oputil to scan the file base area by it’s tag retro_pc and only include the storage tag of retro_pc_bbs. Note that the storage tag could be omitted, and if so, all of retro_pc would be scanned. We have also indicated to #hashtag new entries with the tags “retro”, “bbs”, and “pc”.

For a wildcard storage tag the scan walks all subdirectories automatically:

./oputil.js fb scan --quick --tags scene scene@scene_files

Files found in subdirectories (e.g. 2024/April/somefile.zip) are indexed with their relative path preserved, so two files with the same name in different subdirectories are tracked as distinct entries.

Please see oputil for more information.