You have been redirected from an outdated version of the article. Below is the content available on this topic. To view the old article click here.

Deployment

Starting from Version 2.1, a Structr application can be exported to disk to be synchronized with a source code repository, or imported into a Structr instance.

That includes the user interface (pages, shared components and templates), schema information, business logic, localizations, mail templates, resource access grants, etc. The deployment process provides an easy way to transfer the application to another Structr instance or set up a staging process, and separate the application from its user data.

Deployment workflow

When using a source code repository, the Structr deployment workflow usually includes the following steps.

  1. Set up a Structr instance and create an initial page from template or scratch
  2. Create additional pages, define a first application outline
  3. Mark directories to be included in the export (includeInFrontendExport: true) if applicable
  4. Export an initial version of the application using the command detailed below under Export
  5. Add and commit the initial version to the source code repository
  6. Continue application development
  7. Export application
  8. Add and commit to the repository
  9. Pull and merge changes from collaborators
  10. Import sources using the command detailed below under Import
  11. Go to step #6

Export

To export an application to the directory /tmp/my-structr-app, use the deploy maintenance command with the parameters mode: export and target: /tmp/my-structr-app. The command has to be run with admin privileges.

The following example illustrates the use of curl to export an application on UNIX-based systems.

curl -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/maintenance/deploy -d '{"mode":"export", "target": "/tmp/my-structr-app"}'

If the target directory doesn’t exist, it will be created by the deploy command.

Please note that you must use an absolute path for the target directory.

The minimum filesystem structure of an otherwise empty Structr instance looks like this afterwards:

my-structr-app/
└── webapp
    ├── components
    ├── components.json
    ├── files
    ├── files.json
    ├── localizations.json
    ├── mail-templates.json
    ├── pages
    ├── pages.json
    ├── schema
    │   └── schema.json
    ├── schema-methods.json
    ├── security
    │   └── grants.json
    ├── templates
    └── templates.json

There are directories for each type of category of objects (Pages, Templates, Files and Shared Components) containing the serialized content of the database objects, and a JSON file on the root level for each category, containing meta-data (attributes, permissions etc.) .

The information about custom types is stored in one or more files in JSON Schema format in the schema/ subdirectory. Schema methods are stored in form of a JSON array in the file schema-methods.json on the root level.

Information about the permissions granted to access the REST endpoints are stored in the file security/grants.json.

Import

To import an application from the directory /tmp/my-structr-app, use the deploy maintenance command with the parameters mode: import and source: /tmp/my-structr-app. The command has to be run with admin privileges.

The following example illustrates the use of curl to import an application on UNIX-based systems.

curl -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/maintenance/deploy -d '{"mode":"import", "source": "/tmp/my-structr-app"}'

Please note that you must use an absolute path for the source directory.

Initial configuration

In some cases it will be necessary to apply configuration settings, set up initial users, groups or other data elements. There are two configuration scripts that are applied before and after a deployment. Both files can contain StructrScript or JavaScript expressions like in the following examples. The files need to be placed in the root directory of the export (webapp in the example above).

pre-deploy.conf (JavaScript)

${{
    // Create initial users
    if (Structr.find('User', 'name', 'user1').length === 0) {
        Structr.create('User', {
            name: 'user1',
            password: 'test'
        });
    }
}}

post-deploy.conf (JavaScript)

${{
    // make all pages visible after deployment
    Structr.find('Page').forEach(function(p) {
        p.visibleToAuthenticatedUsers = true;
        p.visibleToPublicUsers = true;
    });
}}

Search results for "Deployment"

DeploymentServlet

deploymentservlet.allowanonymousdeployments Allow anonymous users to trigger a deployment process.
deploymentservlet.allowanonymousuploads Allow anonymous users to upload deployment files.
deploymentservlet.maxfilesize Maximum allowed file size for single file uploads. Unit is Megabytes.
deploymentservlet.maxrequestsize Maximum allowed request size for single file uploads. Unit is Megabytes.

import-data

importData <source> <doInnerCallbacks> <doCascadingDelete>  -  Imports data for an application from a path in the file system.
<source> - absolute path to the source directory
<doInnerCallbacks> - (optional) decides if onCreate/onSave methods are run and function properties are evaluated during data deployment. Often this leads to errors because onSave contains validation code which will fail during data deployment. (default = false. Only set to true if you know what you're doing!)
<doCascadingDelete> - (optional) decides if cascadingDelete is enabled during data deployment. This leads to errors because cascading delete triggers onSave methods on remote nodes which will fail during data deployment. (default = false. Only set to true if you know what you're doing!)

Deployment

deployment.schema.format Specifies the deployment format. Valid values are “file” and “tree”. Preferrably set to “tree” as “file” is the legacy deployment format.

Data Deployment Format

A typical Structr data deployment export has the following export content:

file/folderdescription
nodesContains all export files for configured node types
relationshipsContains all export files for relationships from/to configured node types
pre-data-deploy.confScript that is run before data deployment import. Use this to create users who are granted access to nodes in the export files.
post-data-deploy.confScript that is run after data deployment import. Can be used to start any tasks which are necessary after import.

Deployment Format

folder / filedescription
componentsContains the shared components of the pages editor of Structr.
filesContains all files out of Sturctr’s virtual filesystem. Folders and files in the virtual filesystem are not being exported by default. If you want to include a folder or file into the export you have to set the flag includeInFrontendExport on each file or folder. Each file or folder will inherit this flag from its parent folder.
mail-templatesContains the mail-templates.
modulesContains the application configuration and definition of additional modules of Structr e.g. the flow engine.
pagesContains the created pages in the pages editor of Structr.
schemaContains the schema definition and code entered in the schema and code section of the Structr UI.
securityContains the resource access grants defined in the security section of the Structr UI.
templatesContains all template elements of the pages editor of Structr.
application-configuration-data.jsonContains the configured schema layouts of Structr’s schema editor.
components.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the components folder of the export.
deploy.confContains information about the Structr system that created the export of the application.
files.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the files folder of the export.
localizations.jsonContains the localizations that where created in the localizations section of the Structr UI and that can be used in server side scripting with the localize() function of Structr.
mail-templates.jsonContains the settings e.g. visiblity flags, locale or uuid for each file in the mail-templates folder of the export.
pages.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the pages folder of the export.
pre-deploy.confScript that is run before deployment import. Use this to create users who are granted access to nodes in the export files.
post-deploy.confScript that is run after deployment import. Can be used to start any tasks which are necessary after import.
sites.jsonContains sites that are configured in the pages section of the Structr UI.
templates.jsonContains the settings e.g. visiblity flags, contentType or uuid for each file in the templates folder of the export.
widget.jsonContains the widgets that were created in the pages section of the Structr UI.

Simple Data Model

Changing the schema definition, like in this example by creating a new type, triggers a so-called schema recompilation. A message is displayed that blocks the screen and indicates that the schema is being compiled. Under the hood, the definition graph of the data model is modified, source code is generated from it and validated against the existing schema. When the compilation process is finished, the updated schema definition is available in all parts of the entire application without delay and any further deployment steps.

Deployment

The deployment section is an access point to maintenance functionality that can be used to deploy a new Structr application or export the currently deployed one. More precisely, structr allows to import and export both the application itself, as well as user data, from and to a local directory on the host system that runs Structr (not a directory on the user’s machine or in the Structr filesystem). This is usually the recommended way when an application is built with the help of a version-control tool like git or subversion.

If you want to work in a larger team on a Structr application, or want to use a version-control software like git, you can use the deployment functionality of Structr.

What is Structr?

You can carry out every step of the development process in Structr and only need your web browser: Development, testing, integration, operation and maintenance. Structr enables very short development iteration cycles, while allowing team collaboration and staged deployments.

Features

You can develop applications with the integrated web-based development environment (Structr UI), allowing to manage HTML pages and markup elements as well as application logic in one tool, leading to very short development iteration cycles.

Collaboration of multiple developers using a version control system (e.g. git, SVN, etc.) is of course also possible, as well as the option to establish a staged deployment workflow.

deploy

Creates a Deployment Export or Import of the application. This command reads or writes a text-based export of the application (without its data!) that can be stored in a version control system. The maintenance command is used internally in the Dashboard section.

Name Value
mode deployment mode (import/export)
source source directory when importing
target target directory when exporting
extendExistingApp incremental import (true/false)

deployData

Creates a Data Deployment Export or Import of the application data. This command reads or writes a text-based export of the application data (not the application itself) that can be stored in a version control system.

Name Value
mode deployment mode (import/export)
source source directory when importing
target target directory when exporting
types comma-separated list of data types to export

Data Deployment Import

Go to the ‘Dashboard’ section of the Structr UI into the tab Deployment. Enter the data path as an absolute path of the local file system into the input field Import data from local directory and click on the button.

Deployment Export

Go to the ‘Dashboard’ section of the Structr UI into the tab Deployment. Enter the export location as an absolute path of the local file system into the input field Export application to local directory and click on the button.

If you want to export your Structr application to a remote target system you can do so by clicking the button Export and download application as ZIP file in the ‘Dashboard’ section of the Structr UI under the tab Deployment.

Deployment Import

Go to the ‘Dashboard’ section of the Structr UI into the tab Deployment. Enter the application’s path as an absolute path of the local file system into the input field Import application from local directory and click on the button.

If you want to import an Structr application from a remote system you can put the source code of the exported application into a ZIP file on a remote location. Enter that location into the field Import application from URL in the ‘Dashboard’ section of the Structr UI under the tab Deployment and click on the button to start the download and import process.

Built-in Properties

Key Description
Include In Frontend Export Should this file/folder (and all subfiles/-folders) be included in the deployment export.
Is Mounted Is this file/folder mounted from the host file system.
Last Seen Mounted if the folder is not mounted, when was it last mounted.
Use As Javascript Library Is this folder used as a server-side javascript library.
Content Type The content type of the given file.
Don’t Cache Is Structr allowed to cache the given file.