Installation

Appmixer Self-Managed package is shipped as a zip archive and allows you to install the Appmixer platform on your own infrastructure or in a cloud-computing platform.

Prerequisites

• Docker

• Docker Compose

• NodeJS v18.15.0 (only for Appmixer CLI)

Installation

First, unzip the appmixer.zip archive and change to the appmixer/ directory.

Install and Start Appmixer

docker-compose --project-name appmixer up

Stop Appmixer

docker-compose --project-name appmixer stop

Now you can open the Appmixer Frontend in your browser at http://localhost:8080. Before you start creating flows with applications that require user authentication (OAuth), read this section.

Stop and Clean Up

Stop Appmixer and remove all containers and images:

docker-compose --project-name appmixer down --volumes --remove-orphans --rmi all

Using Webhook Components

Some components require that the Appmixer engine URL is accessible on the Internet. This is especially true for any component that uses webhooks. In order to get these components working on your local machine, you need to set the APPMIXER_API_URL environment variable on the Appmixer engine to point to a public URL. When using the Appmixer trial on your local machine, we recommend using the ngrok utility:

$ ngrok http 2200
ngrok by @inconshreveable                                                                                                                                                                                                                     (Ctrl+C to quit)

Session Status                online
Account                        (Plan: Basic)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://568284c4.ngrok.io -> http://localhost:2200
Forwarding                    https://568284c4.ngrok.io -> http://localhost:2200

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Copy the URL it gives you, in our case https://568284c4.ngrok.ioand replace the following line in the docker-compose.yml file in the root directory of the Appmixer package:

  engine:
    ...
    environment:
      - APPMIXER_API_URL=${APPMIXER_API_URL:-http://localhost:2200}
    ...

with the URL from ngrok:

engine:
    ...
    environment:
      - APPMIXER_API_URL=https://568284c4.ngrok.io
    ...

Now restart Appmixer:

docker-compose --project-name appmixer down # or kill existing with Ctrl-c
docker-compose --project-name appmixer up

Or you can keep the docker-compose.yml file as it is and run it with:

APPMIXER_API_URL=https://568284c4.ngrok.io docker-compose --project-name appmixer up

But this command will set the GRIDD_URL to https://568284c4.ngrok.io as well. See more information about GRIDD___URL here.

The information about automatic setting the GRIDD_URL is valid only when our docker-componse.yml file is used. When you run Appmixer without it, the GRIDD_URL has to be set. This variable affects the OAuth redirect URL.

Creating an Admin User

Users in Appmixer can have a special "admin" scope defined which gives them access to the entire system. Such users have access to all flows and all users and also access to the Backoffice UI application that gives these admin users an overview of users and flows in the system. Due to security reasons, the only way to give a user the "admin" scope is to modify a user record right inside the MongoDB database:

docker-compose -p appmixer exec mongodb mongo appmixer --quiet --eval 'db.users.update({"email": "[e-mail]"}, { $set: {"scope": ["user", "admin"]}})'

Replace the "[e-mail]" email address with an email address of an existing user which you want to grant admin rights. If you don't have a user created yet, please continue to the next "Getting Started" section to see how you can create one using the Appmixer Front-end UI interface. The command above should have the following output:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

As you can see, we have set the "scope" property on our user record to ['user', 'admin']. From now on, our user will have admin rights. Now you can sign-in to the Backoffice UI at http://localhost:8081 using the email address and password of your admin user. If you visit the Users page, you should see something like this:

Enabling Users to Publish Custom Components

Once you have your admin user created. You can use the Backoffice UI to enable users to upload custom components. This can be done by setting the "Vendor" property on your users. Only users with the "Vendor" property set can upload components and only those components that have a matching [vendor] in their names. For example, component "appmixer.utils.forms.CreateForm" can only be uploaded by a user who has "Vendor" set to "appmixer".

Note that the Appmixer Trial package automatically sets the "appmixer" vendor on ALL newly created users so any user of the Trial package can publish custom components with no extra action required.

It is a good practice to set the "appmixer" vendor so that you can upload all of the connectors we provide without modifying all the component/service/module names:

From now on, my "[e-mail]" user will be able to publish new custom components using the appmixer CLI tool.