« About File Areas MENU ACS »

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
}

On their own, storage tags don’t do anything — they are simply pointers to storage locations on your system.

Remember that paths are case sensitive on most non-Windows systems!

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`		Friendly area name.
`desc`		Friendly area description.
`storageTags`		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`		If present, provides the sort key for ordering. `name` is used otherwise.
`hashTags`		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 Uploads for more information.

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.

« About File Areas ACS »