exothermic-story-mapping

README

Exothermic Story Mapping

Exothermic is an open source agile story mapping tool, though storyboards are generic enough to be used for multiple excercises.

Each storyboard has the ability to add goals (rows), columns, and stories.

Uses WebSockets and Svelte frontend framework for a truly Reactive UI experience

Running in production

Use latest docker image

docker pull stevenweathers/exothermic-story-mapping

Use latest released binary

Configuration

Exothermic may be configured through environment variables or via a yaml file config.yaml located in one of:

• /etc/exothermic/
• $HOME/.config/exothermic/
• Current working directory

Example yaml configuration file

http:
  domain: exothermic.dev
db:
  host: localhost
  port: 5432
  user: thor
  pass: odinson
  name: exothermic

Required configuration items

For Exothermic to work correctly the following configuration items are required:

Option	Environment Variable	Description	Default Value
http.domain	APP_DOMAIN	The domain/base URL for this instance of Exothermic. Used for creating URLs in emails.	exothermic.dev
http.cookie_hashkey	COOKIE_HASHKEY	Secret used to make secure cookies secure.	pyrom-maniac

Database configuration

Exothermic uses a Postgres database to store all data, the following configuration options exist:

Option	Environment Variable	Description	Default Value
db.host	DB_HOST	Database host name.	db
db.port	DB_PORT	Database port number.	5432
db.user	DB_USER	Database user id.	thor
db.pass	DB_PASS	Database user password.	odinson
db.name	DB_NAME	Database instance name.	exothermic
db.sslmode	DB_SSLMODE	Database SSL Mode (disable, allow, prefer, require, verify-ca, verify-full).	disable

SMTP (Mail) server configuration

Exothermic sends emails for user registration related activities, the following configuration options exist:

Option	Environment Variable	Description	Default Value
smtp.host	SMTP_HOST	Smtp server hostname.	localhost
smtp.port	SMTP_PORT	Smtp server port number.	25
smtp.secure	SMTP_SECURE	Set to authenticate with the Smtp server.	true
smtp.identity	SMTP_IDENTITY	Smtp server authorization identity. Usually unset.
smtp.sender	SMTP_SENDER	From address in emails sent by Exothermic.	no-reply@exothermic.dev

Optional configuration items

Option	Environment Variable	Description	Default Value
http.port	PORT	Which port to listen for HTTP connections.	8080
http.secure_cookie	COOKIE_SECURE	Use secure cookies or not.	true
http.backend_cookie_name	BACKEND_COOKIE_NAME	The name of the backend cookie utilized for actual auth/validation	userId
http.frontend_cookie_name	FRONTEND_COOKIE_NAME	The name of the cookie utilized by the UI (purely for convenience not auth)	user
http.path_prefix	PATH_PREFIX	Prefix added to all application urls for shared domain use, in format of /{prefix} e.g. /exothermic
analytics.enabled	ANALYTICS_ENABLED	Enable/disable google analytics.	true
analytics.id	ANALYTICS_ID	Google analytics identifier.	UA-161935945-1
config.avatar_service	CONFIG_AVATAR_SERVICE	Avatar service used, possible values see next paragraph	goadorable
config.toast_timeout	CONFIG_TOAST_TIMEOUT	Number of milliseconds before notifications are hidden.	1000
config.allow_guests	CONFIG_ALLOW_GUESTS	Whether or not to allow guest (anonymous) users.	true
config.allow_registration	CONFIG_ALLOW_REGISTRATION	Whether or not to allow user registration (outside Admin).	true
config.default_locale	CONFIG_DEFAULT_LOCALE	The default locale (language) for the UI	en
config.allow_external_api	CONFIG_ALLOW_EXTERNAL_API	Whether or not to allow External API access	false
config.show_active_countries	CONFIG_SHOW_ACTIVE_COUNTRIES	Whether or not to show active countries on landing page	false
config.cleanup_storyboards_days_old	CONFIG_CLEANUP_STORYBOARDS_DAYS_OLD	How many days back to clean up old storyboards, e.g. storyboards older than 180 days. Triggered manually by Admins .	180
config.cleanup_guests_days_old	CONFIG_CLEANUP_GUESTS_DAYS_OLD	How many days back to clean up old guests, e.g. guests older than 180 days. Triggered manually by Admins.	180
auth.method	AUTH_METHOD	Choose normal or ldap as authentication method. See separate section on LDAP configuration.	normal

Avatar Service configuration

Use the name from table below to configure a service - if not set, goadorable is used. Each service provides further options which then can be configured by a user on the profile page. Once a service is configured, drop downs with the different sprites become available. The table shows all supported services and their sprites. In all cases the same ID (ead26688-5148-4f3c-a35d-1b0117b4f2a9) has been used creating the avatars.

Name
goadorable (internal)
govatar (internal)	male	female
dicebear	male	female	human	identicon	bottts	avataaars	jdenticon	gridy	code
gravatar	mp	identicon	monsterid	wavatar	retro	robohash
robohash	set1	set2	set3	set4

LDAP Configuration

If auth.method is set to ldap, then the Create Account function is disabled and authentication is done using LDAP. If the LDAP server authenticates a new user successfully, the Exothermic user profile is automatically generated.

The following configuration options are specific to the LDAP authentication method:

Option	Environment Variable	Description
auth.ldap.url	AUTH_LDAP_URL	URL to LDAP server, typically ldap://host:port
auth.ldap.use_tls	AUTH_LDAP_USE_TLS	Create a TLS connection after establishing the initial connection.
auth.ldap.bindname	AUTH_LDAP_BINDNAME	Bind name / bind DN for connecting to LDAP. Leave empty for no authentication.
auth.ldap.bindpass	AUTH_LDAP_BINDPASS	Password for the bind.
auth.ldap.basedn	AUTH_LDAP_BASEDN	Base DN for the search for the user.
auth.ldap.filter	AUTH_LDAP_FILTER	Filter for searching for the user's login id. See below.
auth.ldap.mail_attr	AUTH_LDAP_MAIL_ATTR	The LDAP property containing the user's emil address.
auth.ldap.cn_attr	AUTH_LDAP_CN_ATTR	The LDAP property containing the user's name.

The default filter is (&(objectClass=posixAccount)(mail=%s)). The filter must include a %s that will be replaced by the user's login id. The mail_attr configuration option must point to the LDAP attribute containing the user's email address. The default is mail. The cn_attr configuration option must point to the LDAP attribute containing the user's full name. The default is cn.

On Linux, the parameters may be tested on the command line:

ldapsearch -H auth.ldap.url [-Z] -x [-D auth.ldap.bindname -W] -b auth.ldap.basedn 'auth.ldap.filter' dn auth.ldap.mail auth.ldap.cn

The -Z is only used if auth.ldap.use_tls is set, the -D and -W parameter is only used if auth.ldap.bindname is set.

Developing

Building and running with Docker (preferred solution)

Using Docker Compose

docker-compose up --build

Using Docker without Compose

This solution will require you to pass environment variables or setup the config file, as well as setup and manage the DB yourself.

docker build ./ -f ./build/Dockerfile -t exothermic:latest
docker run --publish 8080:8080 --name exothermic exothermic:latest

Building

To run without docker you will need to first build, then setup the postgres DB, and pass the user, pass, name, host, and port to the application as environment variables

DB_HOST=
DB_PORT=
DB_USER=
DB_PASS=
DB_NAME=

Install dependencies

go get
npm install

Build with Make

make build

OR manual steps

Build static assets

npm run build

Build for current OS

go build

Running with Watch (uses webapp dist files on OS instead of embedded)

npm run autobuild
make dev-go

Run Locally

Run the server and visit http://localhost:8080

Adding new Locale's

Using svelte-i18n Exothermic now supports Locale selection on the UI (Default en-US)

Adding new locale's involves just a couple of steps.

1. First add the locale dictionary json files in frontend/public/lang/default/ and frontend/public/lang/friendly/ by copying the en.json and just changing the values of all keys
2. Second, the locale will need to be added to the locales list used by switcher component in frontend/config.js locales object

Donations

For those who would like to donate a small amount for my efforts or monthly hosting costs of Exothermic.dev I accept paypal.