Appsemble

The app building platform

Table of Contents

• Usage
• Live Environments
• Requirements
• Getting started
  • CLI Login
  • Registering an Organization
  • Publishing Blocks
  • Publishing App templates
• Development Server
• Tests
• Building
• Contributing
• Security
• License

Usage

These are instructions for developing the Appsemble core platform. Production setup instructions can be found in here.

Live Environments

Our production environment is available on appsemble.app.

Our staging environment is available on staging.appsemble.review. This environment hosts the latest changes in the main branch. This environment is reset every night at 04:00 AM UTC.

For each of our internal merge requests a review environment is started at ${CI_MERGE_REQUEST_IID}.appsemble.review.

Requirements

Minimum Hardware Requirements

Software Requirements

In order to run the Appsemble project in development mode on Linux, macOS or Windows, the following must be installed.

• Docker
• Docker Compose
• NodeJS 18

Getting started

Clone and setup the project.

Note: your CLI should have elevated privileges when setting up and starting the app

git clone https://gitlab.com/appsemble/appsemble.git
cd appsemble
npm ci

The project requires a PostgreSQL database. This project contains a Docker Compose configuration to spin up a preconfigured database with ease.

docker compose up -d

The project can be served using the following command.

npm start

To see additional options, run the following command.

npm start -- --help

CLI Login

A new account can be registered by going to http://localhost:9999/register. Later you can login on http://localhost:9999/login. You can use any email address as long as it satisfies the email format of user@email-provider.ext. As the email is sent from the localhost environment, it is actually not received by the user instead the email containing the verification link will be printed in the server logs. You need to click this link in order to verify you email and use your account. If you connect your localhost environment to an SMTP server, this email will be sent normally and you will receive the verification link. Similarly, if you login using GitHub, Gitlab or Google, you will be authenticated from your account.

To login using the Appsemble CLI, run the following command.

npm run appsemble login

Note: when using Windows Subsystem for Linux (WSL), this command is unsupported. The workaround for this is manually creating OAuth2 credentials at http://localhost:9999/settings/client-credentials and passing them to the CLI by setting the APPSEMBLE_CLIENT_CREDENTIALS environment variable. More details.

This will open Appsemble studio in a new window in your browser. A panel will pop up where you must select the permissions you need. You will need to select at least blocks:write, organizations:write and apps:write to complete the steps below. Clicking confirm creates an OAuth2 access token, which is required in order to publish blocks and apps. Click register and your OAuth2 client credentials will be shown. This will be required when you proceed with the publishing blocks and apps steps below.

Registering an Organization

To get started developing locally, an Appsemble organization identified through id: appsemble needs to be created. This organization can be created either in Appsemble Studio, or using the following CLI command.

npm run appsemble organization create --name Appsemble appsemble

Publishing Blocks

After logging in to the CLI, Appsemble blocks can be published locally by running the following command.

npm run appsemble block publish blocks/*

If prompted, select the OAuth2 credential you created earlier to proceed. You will now see the published blocks in the Block store page.

Any block that is found within the workspaces listed in package.json will be hot-reloaded. More information about block development and hot-reloading can be found here.

Publishing App templates

In order for users to create apps from within the Appsemble Studio, existing apps that can be used as a starting point must be marked as templates. This can be done using the Appsemble CLI, after logging in. To publish these apps, run the following command.

npm run appsemble app publish --context development apps/*

The published apps will be displayed on the App store page.

Development Server

The development server can be started by running:

npm run appsemble serve <path-to-app-directory>

See the CLI readme

Tests

Tests can be run using the following command.

npm test

The tests are ran using vitest, meaning all vitest CLI options can be passed.

By default, database tests are run against the database as specified in docker-compose.yml. The database can be overridden by setting the DATABASE_URL environment variable. Note that this should not include the database name. Multiple test databases are created at runtime.

DATABASE_URL=postgres://admin:password@localhost:5432 npm test

Building

The Appsemble Docker image can be configured using environment variables. Each variable can also be passed as a command line parameter instead, if desired. This includes adding variables for connecting to an SMTP server.

The full explanation of setting up your local server, including a full list of environment variables, can be found at packages/server/README.md.

The resulting Docker image can be built using the Docker CLI.

docker build --tag appsemble .

Contributing

Please read our contributing guidelines.

Security

Please read our security policy.

License

LGPL-3.0-only © Appsemble