appcontrol v0.0.10

WHAT?

AppControl is a tool for the quick deployment of client side web apps (such as those from create-react-app) and NodeJS server apps to Ubuntu servers.

It provides simple easy to use commands to build and deploy your apps, automatically generating Nginx server configuration and Letsencrypt SSL certificates.

Deploying to any Debian derived SystemD supporting OS might work but this is untested.

Installation

AppControl is a NodeJS app. First install NodeJS, then install AppControl with:

npm install -g appcontrol

Basic tutorial

This shows how to deploy a static web app to a single server.

1. Create a new web app (e.g. using create-react-app or similar)
2. Generate a ed25519 key pair, if you don't already have one, using appcontrol keygen
3. Provision a new Ubuntu server using this ed25519 key.
4. Add the server to appcontrol's database: appcontrol addserver
5. In the directory above your app, create a basic deployment config: appcontrol init.
6. Create a release of all your apps in their current state: appcontrol release
7. Deploy to the default "production" deployment target: appcontrol deploy production

et voila! Your app should now be accessible from the interwebs. You can also combine the last two steps using the command appcontrol quickrelease production to perform a release and deploy in one step.

Some further things you might want to do / be aware of:

• appcontrol init will create the deploy config file appcontrol.json in the current directory, and also an app specific config file app.json in your app's directory
• make sure your app's domain has its DNS records propagated and pointing to the desired server before deploying, otherwise getting SSL certificates will fail (alternatively, appcontrol supports Letsencrypt DNS validation, but that requires a bit more configuration)
• if your app has a build step, edit the app.json file in your app's directory to set the correct buildCmd and buildPath. create-react-apps are currently autodetected and will use the default CRA build command.

Future of Appcontrol

AppControl is very much a work in progress. There may be breaking changes in the future!

Todo

• clean up commands (various things are not cleaned up that should be, e.g. certificates will keep being requested for a domain even if you stop using that domain or change from HTTP to DNS verification)
• various server management commands are needed (for example to list all apps on a server, and check running app status)
• release rollback command (for now you can: 1. delete the most recent release, 2. decrement latestReleaseNum in .appcontrol/database.json, and re-deploy... )
• (maybe) support for other server runtimes such as NextJS, Python or PHP.
• (maaaybe) some kind of docker app support

Command overview

Command environmental variables

Environmental variables that affect the operation of AppControl commands.

Configuration files and project structure

Project structure

AppControl expects all apps in a given deployment to be stored in the same "project directory", adjacent to your project's deployment config file appcontrol.json. AppControl will create the hidden directory .appcontrol in your project directory, which contains some deployment state and key pairs, and by default, the built releases of your apps.

Project configuration

There are three main configuration files:

• appcontrol.json in your project's directory. This stores information regarding what apps in your project will be deployed to what servers for what named deployments, and other per project config including any environmental variables for your app's different deployments. Also referred to as the "deploy config".
• app.json in an app's directory. The presence of an app.json file indicates that this folder contains an app that should be released and deployed via AppControl. The app.json can contain some configuration specific to that app, such as a build command.
• ~/.appcontrol.json in your home directory. This contains the definitions of all servers you add to appcontrol via appcontrol addserver (IP addresses, fingerprints), plus it may contain some global config which you want to apply to all your projects.

Environmental variables

Environmental variables can be specified in many different locations:

• an individual app's app.json
• global env in appcontrol.json (applying to all apps across all deployments)
• env specified in a specific deployment block (e.g. staging, production), applying to all servers and apps in that deployment
• env specified for a specific app within a server block

All env is overloaded in the order listed above, with latterly specified env taking precedence. As well as simple "env" blocks in the config, there are more advanced forms…

Within the same block, the different env, envClient, envServer, etc, take precedence as in the order given above. Please see the examples below to see how to use env blocks correctly.

AppControl environmental variables

AppControl provides apps (where relevant) with some utility env vars:

Env vars relating to ports, writable directories, and other server side things will only be present on server apps.

Env block examples

"env" : {
	"TEST_CDN" : "https://cdn.test-all-apps.com"
},

"envClient" : {
	"TEST_CDN" : "https://cdn.test-client-apps-only.com"
},

"envServer" : {
	"TEST_CDN" : "https://cdn.test-server-apps-only.com"
},

"envShared" : [
	{
		"apps" : ["my-app-1", "my-app-2"],
		"env" : {
			"TEST_CDN" : "https://cdn.my-app-1-and-2-only.com"
		}
	}
],

"envApp" : {
	"my-app-99" : {
		"TEST_CDN" : "https://cdn.my-app-99-only.com"
	}
}

Injecting env vars into web apps

Environmental variables can be injected into web apps using a very basic templating mechanism. Unlike some systems, with AppControl these are injected after the build step, and not during it. This is so the exact same build can be deployed to different targets, and with different configuration. There are two ways env vars can be injected; either individual variables or all at once as a JSON string.

In order for a web app to have env vars injected the property injectEnv must be present in its app.json, and must be set to a regex that will match any file names in which you want to have env injected (for example, "\\.(js|html)$" to match all js or html files)

Example injecting env into a HTML script tag under the global "process.env":

<script>var process={env : ###APPCONTROL_JSON_ENV###}</script>

Example injecting a single env var named "MYCDN", a custom CDN string, into HTML:

<img src="###APPCONTROL_ENV_MYCDN###/cat.jpg">

Those examples would require the following app.json, assuming both files end in .html:

{
	"injectEnv" : "\\.html$"
}

Webpack example

If you are using webpack, you might want to have separate webpack development and production configurations. You can then use webpack's htmlPluginOptions like thus:

<script>var process={env : <%= htmlWebpackPlugin.options.appcontrolJsonEnv %>}</script>

Then, in your development webpack config you can set whatever custom env you want under appcontrolJsonEnv, and in your production config you can instead output only the string "###APPCONTROL_JSON_ENV###" which will be replaced during deployment by AppControl with your production env.

app.json

Everything in the app.json is optional. An empty app.json indicates a client side web app with no build step. The app.json file will be skipped during deployment.

Example

{
	"runtime" : "node:20",
	"main" : "server.js",
	"buildCmd" : "npm build",
	"buildPath" : "build/"
	"injectEnv": "\\.(js|html)$"
	"env" : {
		"NODE_OPTIONS" : "--max-old-space-size=800"
	}
}

Properties

appcontrol.json

Minimal example

This deploys a single web app "example-basic-html" to the server 192.168.1.99, with the domain and path example.com/example-basic-html, and will use Letsencrypt's default HTTP verification method for getting the SSL certificate.

{
	"deployments" : {
		"staging" : {
			"servers" : {
				"192.168.1.99" : {
					"apps" : [
						{
							"app" : "example-basic-html",
							"domain" : "example.com",
							"webPath" : "/example-basic-html"
						}
					]
				}
			}
		}
	}
}

Very Long Example

This uses the Letsencrypt DNS verification method along with an alias domain, and deploys to the server with the hostname appcontrol-test (named when adding the server to appcontrol). You can of course have more than one server under the "servers" block, but that would make this a very very long example.

{
	"letsencrypt" : {
		"dns_hook" : "dns_gandi_livedns",
		"challenge_alias_domain" : "mydomain.com",
		"env" : {
			"GANDI_LIVEDNS_KEY" : "1234567890"
		}
	},
	
	"env" : {
		"EXAMPLE_VAR" : "this var present for all apps across all deployments"
	},
	
	"deployments" : {
		"staging" : {
			"masterServer" : "appcontrol-test",
			
			"env" : {
				"EXAMPLE_VAR" : "present for all apps in this staging deployment"
			},
			
			"envClient" : {
				"CLIENT_VAR" : "present for all web apps in staging"
			},
			
			"envServer" : {
				"SERVER_VAR" : "present for all server apps in staging"
			},
			
			"envShared" : [
				{
					"apps" : ["example-basic-html", "example-node-server"],
					"env" : {
						"EXAMPLE_VAR" : "present for just the apps listed above"
					}
				}
			],
			
			"envApp" : {
				"example-node-server" : {
					"EXAMPLE_VAR" : "present for this one named app, across all servers in this deployment"
				}
			},
			
			"servers" : {
				"appcontrol-test" : {
					"redirects" : [
						{
							"domain" : "old.example.com",
							"destination" : "https://new.example.com/$request_uri",
							"code" : 301
						},
						{
							"domain" : "old.example.com",
							"regex" : "^/page/(.+)$",
							"destination" : "https://new.example.com/new_page/$1",
							"code" : 301
						}
					],
					"apps" : [
						{
							"app" : "example-basic-html",
							"domain" : "example.com",
							"webPath" : "/example-basic-html"
						},
						{
							"app" : "example-node-server",
							"domain" : "example.com",
							"webPath" : "/example-node-server",
							"instancesPerCPU" : 1,
							"dataGroup" : "nodeservergroup",
							"env" : {
								"EXAMPLE_VAR" : "env for this app only on this specific server"
							}
						},
						{
							"app" : "example-node-daemon"
						}
					]
				}
			}
		}
	}
}

Properties

Top level

Letsencrypt block

These properties can be present in the letsencrypt block. These configuration options relate to using the Letsencrypt DNS API to get certs. This is useful if for whatever reason you don't yet have the correct DNS records set up for your servers and so can't use the simpler HTTP verification.

Deployment blocks

A deployment block can contain the following properties:

Server block

A server IP address or hostname may be used as a property of the deployment block, and the object it points to will be a server block. A server block may contain:

App blocks

Redirect blocks

These blocks should be considered experimental and used carefully, as putting the wrong thing as a regex or destination could easily break your nginx config. Redirecting a domain that is already used by an app might also cause fun problems. It's recommended to check the generated nginx config carefully on a test server before deploying to production. You have been warned.

These are mostly intended for when you move a website or API to a new domain and need to redirect from the old one, with the old domain being obsolete and having no apps using it. See the long appcontrol.json example earlier in the docs.

The global .appcontrol.json

The file .appcontrol.json in your home directory is more of a database that generally shouldn't be edited, however you can add some global things here.

That's all folks

Congratulations on scrolling this far.