Usage¶
marble¶
Tool for deploying Socrata homepage templates.
Usage:
marble [OPTIONS] COMMAND [ARGS]...
Options:
-V, --version Show the version and exit.
--help Show this message and exit.
assets¶
Upload a file to the Socrata assets service.
Usage:
marble assets [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
--file FILENAME File to upload. [required]
--no-config-update Do not update config file with asset URL.
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
convert¶
Convert a Chalk project to a Marble project.
After converting a project, you must still reverse-populate datasets
from the domain. It is also common for conversions to break certain
dependencies, components, or styles; be sure to run your project
locally before attempting to deploy.
Usage:
marble convert [OPTIONS]
Options:
--template [rally|cityscape|covid|evergreen|homebase]
Socrata homepage template to use for the
project. [default: rally; required]
--auth-env [fedramp|rc|staging|eu]
The domain's Socrata authentication
environment. [default: fedramp; required]
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
default¶
Get or set the default Marble config file in .marble_default.
Reads or writes the configuration file path set in the local
.marble_default file. If a simple shortcut such as "staging" or
"prod" is passed, Marble will look up the associated config file
(for example, "staging.marble.yml") in the local site_configs
directory.
Usage:
marble default [OPTIONS] [CONFIG_FILE_PATH]
Options:
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
generate¶
Generate a new Socrata homepage project.
Pulls down the latest version of the socrata_templates repository
and initializes a new project directory according to the supplied
parameters.
Usage:
marble generate [OPTIONS]
Options:
--domain TEXT Socrata domain to use for the project.
[required]
--template [rally|cityscape|covid|evergreen|homebase]
Socrata homepage template to use for the
project. [default: rally; required]
--homepage-permission [public|domain_private|private]
Homepage view permission. For ODP, this is
typically 'public'. For EDP, this is
typically 'domain_private'. 'private' will
make the homepage viewable only by admins.
[default: public; required]
--auth-env [fedramp|rc|staging|eu]
The domain's Socrata authentication
environment. [default: fedramp; required]
--repo-name TEXT Repository name. [required]
--branch TEXT Git branch or tag to pull from
socrata_templates. [default: main]
--parent-dir DIRECTORY Parent directory in which the project will
be created. [default: ./]
--config-name TEXT Name to use when generating an initial
config file. [default: staging]
--push-git / --no-push-git Push the project to a remote Bitbucket
repository after generating. [required]
--skip-dep-check / --no-skip-dep-check
Skip external dependency check. [default:
no-skip-dep-check]
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
populate¶
Upload all datasets and associated images to a domain.
Usage:
marble populate [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
--delete Delete existing datasets before populating new ones
onto domain.
--no-sort-order-column Disables requirement that a 'sort_order' column be
present in the dataset
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
publish¶
Publish one or more pages to the Socrata pages service.
If a directory is specified, will crawl the directory tree and
attempt to publish any file with an extension of .json, .yaml, or
.yml.
Usage:
marble publish [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
--file PATH Page file (YAML or JSON), or directory of such
files, to publish. [required]
--validate-path Validate that a page's filepath matches its path
property.
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
reverse-populate¶
Download a domain's configuration datasets and images.
Usage:
marble reverse-populate [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
upload-all¶
Upload CSS, JS, and page web content to a domain.
This is a convenience command that executes the following commands
in turn. The filepath passed via --publish-file is forwarded to the
publish command's --file parameter.
marble upload-app
marble upload-css
marble upload-js
marble publish --file PATH
Usage:
marble upload-all [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
--publish-file PATH Page file (YAML or JSON), or directory of such
files, to publish. [required]
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
upload-app¶
Upload app JS files to the Socrata assets service.
Usage:
marble upload-app [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
upload-css¶
Upload CSS to the Socrata configurations service.
Usage:
marble upload-css [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
upload-js¶
Upload site administration JS files to the Socrata configurations service.
Usage:
marble upload-js [OPTIONS]
Options:
-c, --config FILE Marble config file to use. If .marble_default exists
in the current working directory, defaults to the
config file specified therein.
-v, --verbose Enable verbose logging.
-l, --log-to-file FILE Log to the specified filepath.
--help Show this message and exit.
Default file¶
A .marble_default file is created when you run marble generate to start a project. .marble_default should always exist at the root level of your project; Marble uses it to tell which configuration file to use when deploying.
You can read or update your project's .marble_default by executing marble default within your project directory. This is handy when, for example, you want to tell Marble to use a production configuration file instead of staging.
Here's the content of an example .marble_default file:
./site_configs/staging.marble.yml
Configuration file¶
When you execute marble generate, Marble creates two YAML configuration files (staging.marble.yml, prod.marble.yml) under the site_configs directory of your project. Each configuration file represents the Marble settings, paths, and identifiers needed to deploy a website to a particular domain or environment.
If you change a given configuration file, e.g. to modify a domain name, Marble will then use the updated value going forward.
Here's an example of the configuration file structure:
app_dir: ./dist/app
assets: {}
assets_dir: ./assets/
auth_env: fedramp
css_dir: ./dist/css/
dataset_dir: ./datasets/
dataset_images_dir: ./dataset_images/
datasets: {}
domain: some-domain.data.socrata.com
dataset_permission: public
js_dir: ./dist/js/
pages_dir: ./pages/
project_root: ./
use_test_paths: true
version: 1.0.0