nirvash/README.md

NIRVASH

about

nirvash is a content management system (CMS) written in Go using the quartzgun library, designed to be efficient, modular, and easy to use. It uses an Adapter system that in theory allows almost any backend SSG to be used for actual page generation and backend storage. It's inspired by Joost Van Der Schee's Usecue CMS.

installation and configuration

Clone this repository and run go build to build nirvash. Just running ./nirvash from there, if you haven't run it before, should run the configuration wizard (it runs if the config file found in your user's config directory is missing or incomplete). The configuration file looks like:

adapter=eureka // one of the supported adapters, currently just eureka
root=/path/to/ssg/root // path to where your SSG content root is
assetRoot=/path/to/asset/root // path to the parent folder containing Nirvash static/ assets and templates/ directory (eg base directory of this repo)
staticRoot=/path/to/static/root // path to static file storage on your webserver
staticShowHTML=false // true or false, show HTML files in the file manager interface
staticShowHidden=false // true or false, show hidden files in the file manager interface
staticMaxUploadMB=25 // integer, maximum size in MB of files uploaded in the file manager interface
plugins=none // list of plugins to use, currently none are implemented

You can also set the configuration options by running eg nirvash configure adapter=eureka root=/var/www. Key-value pairs given on the command line are written to the configuration file, and pairs not listed are unmodified.

User management is done from the command line as well:

• nirvash adduser username password
• nirvash rmuser username
• nirvash passwd username oldpass newpass

usage

Running nirvash without any arguments starts the webserver on port 8080.

Initially the user will be presented with the login screen; upon successful login, the application presents the navbar with these options:

• Pages: the default page, shows a list of existing pages - clicking one enables editing that page; a button is also presented for adding a new page. Each Adapter will provide different formatting help and can allow editable slugs/URLs or not (eg, the EurekaAdapter builds slugs/URLs directly from the page title).
• Files: provides an interface for managing statically hosted files. Files and directories can be added, moved, and deleted.
• Configuration: interface to the configuration for the Adapter. Each Adapter provides its own configuration interface with associated data types (currently supported: int, float, string, and multilinestring)
• Build: a simple form to build the site - build options configurable by Adapter are present under an accordion.
• Deploy: a very simple form to either deploy the site or revert the current state to the deployed state
• Logout: logs the user out and returns to the login screen

adapter interface

nirvash is extensible by Adapters that can interact with almost any static site generator under the hood.

The Adapter interface and associated data types can be found in the adapter.go file, but the basic interface looks like this:

• Init(cfg *Config): set any initial settings that need to be handled - typically import SSG data root from the nirvash config file and read the SSG's own config file
• Name() string: the name of the adapter, used for the nirvash.conf config file
• EditableSlugs() bool: whether slugs can be edited independently or are calculated based on, eg, page titles
• BuildOptions() []string: a list of names of the build options to present on the /build page
• GetConfig() map[ConfigOption]string: retrieves the config to present on the /config page
• SetConfig(map[ConfigOption]string) error: takes the config from the /config page and applies it, typically by writing it to a file
• ListPages() map[string]string: list the pages in the site; keys are the slugs, values are the titles
• GetPage(slug string) Page: given a slug, return the page data
• FormatPage(string) string: given the raw page data as input by the user, return HTML suitable for preview (currently unimplemented and unused)
• FormattingHelp() string: return a string to be inserted into a pre tag on the /fmt-help page
• CreatePage(slug, title, content string) error: given all the proper arguments, create a new page in the backing store (eg filesystem, db)
• SavePage(oldSlug, newSlug, title, content string) error: given all the proper arguments, save a page to the backing store (eg filesystem, db)
• DeletePage(slug string) error: given a slug, delete the corresponding page source and possibly its generated HTML, depending on the Adapter
• Build(buildOptions map[string][]string) BuildStatus: takes a map of build option names to their values and builds the site, returning a BuildStatus object containing the success or failure as a boolean and the detailed status (eg, the console ouptut of the build process)
• Deploy() DeployStatus: executes the deployment script and returns a DeployStatus object, analagous to a BuildStatus
• Revert() RevertStatus: executes the reversion script and returns a RevertStatus object, analagous to a BuildStatus

license

nirvash is licensed under the MIT license.