You must have an account in 3scale. The CMS contents can be viewed in the
Developer Portal section of the admin portal for that account.
To use the 3scale-cms command you need to provide a few parameters:
-
An ACCESS_TOKEN, which can be used instead of a PROVIDER_KEY. The access token must be granted permissions to both the Account Management API and the Developer Portal API.
-
The PROVIDER_KEY, which can be found in the Account tab of your admin portal (only visible to the users with "admin" role). The PROVIDER_KEY will be ignored if an ACCESS_TOKEN is specified.
-
The PROVIDER_DOMAIN of your admin portal. e.g.
https://mycompany-admin.3scale.net -
The DIRECTORY, which specifies a local directory path for determining files to upload, download, or compare between the local filesystem and the 3scale CMS content. This is an optional parameter. If omitted, the
3scale-cmscommand will choose a working directory following the rules described in this note.
The 3scale-cms command has five actions:
-
info - show information about contents of the CMS and the local files. It accepts the optional parameter: 'details'
-
diff - show the difference in contents between the CMS and the local files. It accepts the optional parameter: 'details'
-
download - download all the contents of the CMS (no parameter). Or specify a file or section (with its contents) to download
-
upload - upload all the local files (no parameter). Or specify a file or section (with its contents) to upload
-
delete - delete all (that can be deleted) or a specific entry in the remote CMS
|
Note
|
The
|
This command displays information about contents of the CMS and the local files. It accepts the optional parameter: 'details'
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN infoOutput should resemble:
Contacting CMS at PROVIDER_DOMAIN/admin/api/cms to get content list
The layout 'main_layout' in file '/l_main_layout.html.liquid' was selected as the default layout for uploading new pages
118 items found in CMS
7 ignored local files (matching patterns in '.cmsignore')
152 (non-ignored) local files
8 implicit folders due to file/template system_names containing '/'Use the following to get a list of specific files in each of these four categories:
-
CMS contents elements
-
Locally ignored files
-
Local files that are not being ignored
-
List of folders created due to CMS elements with '/' in the name
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN info detailsThis command displays the differences in contents (taking into account ignored files and implicit folders) between the CMS and the local files.
Use
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN diffOutput should resemble:
Contacting CMS at PROVIDER_DOMAIN/admin/api/cms to get content list
The layout 'main_layout' was selected as the default layout for uploading new pages
Summary:
0 files to be created locally
0 files to be updated locally
17 files to be created on CMS
1 files to be updated on CMSTo get the list of specific files to be applied on 'download' and 'upload' use:
podman run --rm -it -v .:/cms:Z ghcr.io/fwmotion/3scale-cms PROVIDER_KEY PROVIDER_DOMAIN diff detailsIf used without an additional file/directory name parameter, this command downloads the entire contents of the CMS that either doesn’t exist locally, or is out of date locally (based on timestamps of files/folders).
If a filename is specified, then only that file is downloaded (if it exists in the CMS and is out of date locally).
If a directory name is specified, then it and all its contents (recursively down) are checked and any content that is found to exist in the CMS and is out of date is downloaded.
|
Note
|
Existing files are overwritten on download, and missing files are ignored unless
the Files matching patterns in |
If used without an additional file/directory name parameter, this command uploads all local files found under the current working directory that are either out of date in the CMS (based on timestamps) or do not exist in the CMS.
If a filename is specified, then only that file is uploaded (if it exists in the CMS and is out of date, or does not exist in the CMS).
If a directory name is specified, then it and all its contents (recursively down) are checked and any content that is found to not exist in the CMS or is out of date in the CMS is uploaded.
Files matching patterns in .cmsignore are skipped.
If used without an additional parameter this command will attempt to delete all
content under the root section on the remote CMS (indicated via domain
parameter).
If used with a specific filename it will attempt to delete that entry in the remote CMS.
If used with a folder name, it will attempt to delete that section and all sections and content under it in the CMS.
|
Warning
|
This action cannot be undone, and should be used with caution. Double-check the domain parameter you intend to use. |
The 3scale-cms command enables you to do offline editing, changes or
version control of the contents of a CMS in your admin portal in 3scale.
In the CMS it is possible to create a file, a template or a section. Examples
of files are an image, a JS script, or a CSS stylesheet. A template is generally
content in an .html.liquid file. A section is a hierarchical folder in the CMS
for storing other elements.
The mirror used locally is a hierarchy of folders that mirrors the content organization in the CMS. Thus sections in the CMS are mirrored as directories on your local file system, and the elements below that section in the CMS are placed inside that directory.
|
Note
|
It is possible to create a file/template in the CMS that is served from a path
other than its location in the CMS. e.g. a file called |
It is often desirable to have some files in the local directory that you do not
want to upload to the CMS. Examples could be files used in the version control
of your CMS contents (e.g. a .git folder), or files used in the testing or
Continuous Integration of your contents (e.g. travis.yml file).
To have the 3scale-cms command ignore these files, they can be added to the
.cmsignore file in any directory of the CMS mirror. These files use the
'glob' format to allow specifying patterns of files and directories, not just
specific files.
When a local file of type .html or .html.liquid is created that does not
have the _ (underscore) prefix to indicate it is a partial or the l_
(l-underscore) prefix to indicate it is a layout, then the tool assumes that the
new file is a page and uploads it as such.
|
Note
|
By convention, partial filenames are expected to have the prefix |
When a page is created in the CMS, the layout to apply to it must be specified. To allow for automatic use of the tool without user intervention the tool chooses a default layout from the layouts in the CMS to use for new files it creates.
Upon start-up the tool examines the list of layouts in the CMS and chooses one as the default layout for new pages that will be created.
If no layouts are available in the CMS, the tool will not run.
If you wish to use a different layout for a newly created page, you currently have to go to the CMS in the admin portal and change it manually.