dxfl

dxfl

A CLI tool to manage your Deuxfleurs account.

Install

npm install -g dxfl

Usage

Warning: software still in an experimental state

Start by logging in with your username, for example for john:

dxfl login john

Then you can list your websites:

dxfl list

And then to deploy your _public folder on example.com:

dxfl deploy example.com _public

To deploy without confirmation, use the --yes option:

dxfl deploy example.com _public --yes

Or only display the changes without applying them, with the --dry-run option:

dxfl deploy example.com _public --dry-run

Use the empty command to delete all files from a website (required before deleting it):

dxfl empty example.com

Website configuration

dxfl deploy reads a deuxfleurs.toml configuration file (if it exists in the current directory). This file can be used to specify website configuration metadata such as redirections.

Your deuxfleurs.toml should follow the following structure:

# Filename added after URLs that point to directories.
# Default value: "index.html"
index_page = "index.html"
# Path to the file to serve in case of 404 error.
# Default value: "error.html"
error_page = "error.html"

# A redirect entry. There can be as many as desired.
[[redirects]]
# Source of the redirection.
from = "old/path"
# Target of the redirection.
to = "new/path"

# Redirects can also match multiple paths, by specifying
# a prefix followed by *
[[redirects]]
# Source of the redirection: all paths that match the prefix
# foobar/
from = "foobar/*"
# Target: redirect all foobar/XXX to baz/XXX.
# The target can also be an URL outside of the website, or a
# single path.
to = "baz/*"
# Optional: custom HTTP status code for the redirection.
# Default value: 302
status = 301
# Optional: always apply the redirect.
# By default, redirections that match multiple paths do not apply
# if a file that matches the requested path could be served instead.
# Setting this option to true overrides this behavior and always
# applies the redirection.
# Default value: false
force = true

# Configuration to allow cross-origin requests.
# Multiple rules can be specified and will be matched in order.
# Each rule is defined in its own `[[cors]]` block
[[cors]]
# Origins that you want to allow cross-origin requests from.
allowed_origins = "https://www.example.com"
# Possible values:
# - allowed_origins = "*" : wildcard to allow all origins
# - allowed_origins = "https://www.example.com" : string of origin (protocol+domain)
# - allowed_origins = ["https://example1.com", "https://example2.com"] : array of origins
# Required parameter.

# HTTP methods allowed in a cross-origin request (in response to a preflight request).
allowed_method = "GET"
# Possible values:
# - allowed_method = "*" : wild card to allow all methods (only GET/HEAD are currently supported by the server)
# - allowed_method = "GET" : string of http method ("GET" or "HEAD")
# - allowed_method = ["GET", "HEAD"] : array of string http methods
# Optional parameter. Default value: ["GET", "HEAD"]

# Request headers allowed in a preflight request.
allowed_header = "Authorization"
# Possible values:
# - allowed_header = "*" : wildcard to allow all headers
# - allowed_header = "Authorization" : string of http header
# - allowed_header = ["Authorization", "Age"] : array of string http header
# Optional parameter. Default value : []

# Response headers you want to make available to JavaScript in response to a cross-origin request.
expose_header = "Content-Encoding"
# Possible values:
# - expose_header = "Content-Encoding" : string of http header
# - expose_header = ["Content-Encoding", "Kuma-Revision"] : array of string http header
# Optional Parameter. Default value : []

Using dxfl in automated deployments

dxfl login is designed for interactive use, where you type the password in your local computer. For automated deployments (e.g. deploying your website in a continuous integration workflows), you can instead directly call dxfl deploy (or dxfl empty) and pass website credentials using environment variables:

• AWS_ACCESS_KEY_ID for the S3 key id;
• AWS_SECRET_ACCESS_KEY for the S3 secret key.

The values for these variables can be found in the Guichet web interface for your website in the "S3" tab.

Config examples for Woodpecker CI and GitHub Actions are also available to help you get started.

Development

git clone https://git.deuxfleurs.fr/Deuxfleurs/dxfl
cd dxfl
npm install
# build and install the tool as the `dxfl` command
npm link
dxfl
# alternatively, run the tool from the sources directly
npx dxfl

Code formatting

Prettier is used to assure a certain consistency in style (and accessibility) through the codebase. An EditorConfig file is also here with a similar goal.

You can format your changes with the dedicated npm command lines:

npm run prettier-check # check formatting without making change
npm run prettier # fix formatting
npm run prettier-watch # watch upcoming changes to fix

Release

First you need an account on npmjs.com and be a maintainer of the dxfl package (ask quentin). Do not forget also to run npm login to bind your account with the CLI.

Then to publish a release:

vim CHANGELOG.md # update the version and its content in this file
vim package.json # update the version in this file
vim index.ts # update the version in this file
npm install # update the version in the package-lock.json
npm run prettier # fix potential coding style problem
git commit -a -m 'set version 0.1.5' # commit your change
git push # send update
git tag -m 'v0.1.5' v0.1.5 # create associated tag
git push --tags # push tag
npm publish # build and push the package

License

This software is distributed under the EUPL-1.2 license.