Skip to content

Latest commit

 

History

History
243 lines (142 loc) · 5.67 KB

DEVELOP.rst

File metadata and controls

243 lines (142 loc) · 5.67 KB
Raw

Developer guide

Setup

Install Node.js sandbox and package dependencies:

source bootstrap.sh

Tests

To run the tests, use the following commands:

npm test

Development environment

Quickstart

Start CrateDB:

npm run cratedb

Start the development server on http://localhost:9000/:

npm run develop

After the application has been compiled and the Webpack development server has started, the process should automatically open a browser tab.

Working with production builds locally

You need to build for production:

npm run build

Then, you can start a local server to serve the production build:

npm run serve

This will start a server on http://localhost:8000/.

Description

There is a base_uri parameter intended for development use only. You can use it to specify the URL of your CrateDB instance, like:

http://localhost:9000/?base_uri=http://localhost:4200

When running CrateDB by other means, please make sure to enable Cross-Origin Resource Sharing in your CrateDB configuration, like:

http.cors.enabled: true
http.cors.allow-origin: "*"

Development operations

Adding new dependencies

To add application dependencies, invoke:

npm install [dependency] --save

This dependency should then be imported in ./app/vendor.module.js, for the application to load correctly.

If the dependency is an angular module, it should also be included in MODULES in ./app/app.module.js

To add development dependencies, invoke:

npm install [dependency] --save-dev

Adding new components

When a new component is created (a module or a service or a controller), it should be imported to ./app/app.components.js.

Adding new stylesheets

When a new stylesheet is created it should be imported to ./styles/styles.scss, this applies to both vanilla and vendor stylesheets.

Maintaining dependencies

In order to find critical updates for the packages used as dependencies, run:

npm audit

Then, either run npm audit fix, or edit package.json manually, also taking the overrides section into consideration.

In order to lock the dependencies, updating package-lock.json accordingly, run npm install --package-lock-only.

Plugins

On startup, the conf/plugins.json file is read and plugins (Angular modules) are loaded.

The tutorial plugin is loaded by the default configuration.

Building

To compile the app without development mode, invoke:

source .venv/bin/activate
npm run build

To run the Admin UI as a standalone app, open the build/index.html file in your browser.

Releasing

Preparing a release

Before releasing, run through the Admin UI Release Preflight.

To create a new release, you must:

  • Add the new version to package.json

  • Invoke npm install --package-lock-only in order to update package-lock.json

  • Add a section for the new version in the CHANGES.rst file

  • Commit your changes with a message like "Release x.y.z"

  • Push to origin and create a tag by invoking ./devtools/create_tag.sh

  • Run the admin_ui_release job on Jenkins, using the relevant tag of the new release version

  • Find out about the SHA256 checksum of the release tarball:

    wget https://cdn.crate.io/downloads/releases/crate-admin-1.24.7.tar.gz
sha256sum crate-admin-1.24.7.tar.gz

  • Submit a patch to update Admin UI in CrateDB, like crate/crate#15337

Documentation

The documentation is written using Sphinx and ReStructuredText.

Working on the documentation

Python >= 3.7 is required.

Change into the docs directory:

$ cd docs

For help, run:

$ make

Crate Docs Build

Run `make <TARGET>`, where <TARGET> is one of:

  dev     Run a Sphinx development server that builds and lints the
          documentation as you edit the source files

  html    Build the static HTML output

  check   Build, test, and lint the documentation

  reset   Reset the build cache

You must install fswatch to use the dev target.

Continuous integration and deployment

Documentation version

GitHub Actions is configured to run make check from the docs directory. Please do not merge pull requests until the tests pass.

Read the Docs (RTD) automatically deploys the documentation whenever a configured branch is updated.

To make changes to the RTD configuration (e.g., to activate or deactivate a release version), please contact the @crate/tech-writing team.