Florence

The publishing platform used for the ONS website.

Getting started

To run Florence you must have:

1. Golang installed:

   brew install go

2. nvm installed:

   brew install nvm

   ⚠️ Make sure to follow the instructions provided at the end of the install to configure up your shell profile.

3. The node version specified in .nvmrc installed through nvm:

   nvm install

Once you have installed those dependencies and cloned this repo you need to run the following:

1. Move into the correct directory

   cd florence

2. Build node modules (you won't need to do this everytime only when the assets need to be rebuilt)

   make node-modules

3. Run the server

   make debug

Steps 2 & 3 can also be run with the following command:

make dev

This will build the node modules and then run the server

1. Browse to the Florence homepage http://localhost:8081/florence

2. If you are running Florence for the first time you will need to login with the setup credentials. You will be asked to change this password.

Username: [email protected] Password: Doug4l

Further guidance on how to use Florence can be found in usage.md

Dependencies

There are other ONS digital applications that you'll need to run to allow Florence to work end-to-end:

• Preview: Babbage
• API: Zebedee CMS
• Preview: Sixteens
• Publishing: The Train
• Dataset upload: Import API
• Dataset upload: Recipes API

Optional (for developing Florence)

• Install NodeJS and NPM

• Watch for JS, CSS and other source file changes

  make watch-src

• Update JS, CSS and other source file changes

  make node-modules

Tools

To run some of our tests you will need additional tooling:

Audit

We use dis-vulncheck to do Go auditing, which you will need to install.

For NodeJS auditing we use auditjs which requires you to setup an OSS Index account

Linting

We use v2 of golangci-lint, which you will need to install.

Configuration

The following environment variables are available when running the Go server.

Environment variable	Default	Description
API_ROUTER_URL	http://localhost:23200	The URL of the dp-api-router
BIND_ADDR	:8080	Host and port to bind to. Note: running make debug will run Florence on :8081
ROUTER_URL	http://localhost:20000	URL that the frontend router can be accessed on
ZEBEDEE_URL	http://localhost:8082	URL that Zebedee can be accessed on
IMPORT_API_URL	http://localhost:21800	URL that the dataset import API can be accessed on
RECIPE_API_URL	http://localhost:22300	URL that the dataset recipes API can be accessed on
DATASET_API_URL	http://localhost:22000	URL that the dataset API can be accessed on
TABLE_RENDERER_URL	http://localhost:23300	The URL that dp-table-renderer can be accessed on
DATASET_CONTROLLER_URL	http://localhost:24000	Dataset controller url
GRACEFUL_SHUTDOWN_TIMEOUT	10s	The graceful shutdown timeout in seconds
HEALTHCHECK_INTERVAL	30s	The period of time between health checks
HEALTHCHECK_CRITICAL_TIMEOUT	90s	The period of time after which failing checks will result in critical global check status

The following environment variables are available when running the Go server and within the React application:

Environment variable	Default	Description
ALLOWED_EXTERNAL_PATHS	[]string	Permitted external primary path and subpath from Florence e.g. primary path /data-admin allows /data-admin/*
API_ROUTER_VERSION	v1	The version of the dp-api-router
ENABLE_CANTABULAR_JOURNEY	false	Enables the cantabular journey
ENABLE_MIGRATION_FIELD	false	Enables the management of the migration field
ENABLE_NEW_UPLOAD	false	Enables the image upload functionality via static files service
ENABLE_PERMISSION_API	false

For example:

make debug BIND_ADDR=:20000

Testing

Run all tests

npm run test

Testing a single file

npm run test:file --file=<YOUR_FILE>

Contributing

See CONTRIBUTING for details.

License

Copyright © 2016-2024, Office for National Statistics (https://www.ons.gov.uk)

Released under MIT license, see LICENSE for details.