KNoT Cloud Docker stack.
Stacks for development and production environments are provided in order to assist the user's needs. The development stack must be used if one needs to modify any of the components of the stack. A command line tool will download the source for each component and plug it into the containers, which all have hot reload enabled. The production stack must be used in all other cases.
The provided stacks and CLI contained in this repository aren't yet published in any package manager, hence it is necessary that you clone the repository or download the .zip containing all the files.
git clone https://github.com/CESARBR/knot-cloud.gitThe following instructions always assume you are in the directory created after cloning the repository. If you downloaded the .zip, navigate to the appropriate folder.
If you intend to use the development stack, a command line tool that downloads and configures the stack is required.
The tool is built and installed as follows:
npm install
npm run build
npm linkDepending on npm configurations, it might be necessary to run npm link with super user privileges.
sudo npm linkThe development stack must be created using the tool described in the previous section. Choose a <path> where the stack should be created (defaults to current directory) and then run:
knot-cloud init [path]The source code and stack template files will be created under <path>/stack.
The production stack comes in two flavours: all-in-one and multinode. The former will deploy all the services on a single machine while the latter will deploy them in multiple nodes, at least two. The files for the two flavours are available at stacks/prod.
In your deployment machine, initialize Docker Swarm mode:
docker swarm initIn case you are deploying to multiple nodes, all the nodes must be connected to the same swarm. In this case, run the command above in the machine that must be the swarm manager and run docker swarm join in all other nodes, as instructed by the execution of docker swarm init in the manager machine. Check the Docker Swarm documentation for more on how to setup your cluster.
This stack uses Traefik as a reverse proxy for the services and requires that you configure your DNS server to point, at least, the www, ws, auth and bootstrap subdomains to the machine where the stack is being deployed, so that it can route the requests to the appropriated service. It is possible to configure it to route by path or port, but instructions for that won't be provided here for brevity.
If you don't have a domain or can't configure the main DNS server, you can configure a test domain in your machine before proceeding. Either setup a local DNS server, e.g. bind9, or alternatively update your hosts file to include the following addresses:
127.0.0.1 www
127.0.0.1 ws
127.0.0.1 auth
127.0.0.1 bootstrap
On Windows, the hosts file is usually located under c:\Windows\System32\Drivers\etc\hosts. On Unix systems, it is commonly found at /etc/hosts. Regardless of you operating system, administrator or super user privileges will be required.
Notice that when deploying KNoT Cloud locally, most of the times the <your-domain> subdomains in the following sections should be disregarded. For instance, you would access your KNoT Cloud at https://www after deploy.
Stage 1 contains the core services. The next sections provide the instructions to configure and deploy them. Whenever a configuration file is mentioned, it refers to a file found at stacks/prod/env.d, for production mode, or <path>/stack/dev/env.d, for development mode.
Create, if you already don't have, a private/public key pair:
openssl genpkey -algorithm RSA -out privateKey.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in privateKey.pem -out publicKey.pemThen, convert the keys to base 64:
base64 < privateKey.pem
base64 < publicKey.pemAnd generate a 16-bit random value in hexadecimal format:
openssl rand -hex 16Finally, set TOKEN, PRIVATE_KEY_BASE64 and PUBLIC_KEY_BASE64 to the values above in:
meshblu-core-dispatcher.envmeshblu-core-worker-webhook.envknot-cloud-storage.env
Deploy the stage 1 services:
docker stack deploy -c stage-1.yml knot-cloudWait until all the services are started. You can check it by running:
docker stack services knot-cloudAnd verifying that every service has one replica.
Before bringing the stage 2 services up, a bootstrap process must be executed in the stage 1 services. The next sections provide the instructions to execute this process.
Deploy the stage 2 bootstrap services:
docker stack deploy -c stage-2-bootstrap.yml knot-cloudWait until the bootstrap service is responsive, when the following command should succeed:
curl https://bootstrap.<your domain>/healthcheckNote: If the HTTPS certificates are not configured locally, traefik has a default certificate that is used in such cases. To use traefik's default certificate, it is necessary to add -k parameter to the curl command otherwise the request will fail.
Once the services are started, run the bootstrap process:
curl -X POST https://bootstrap.<your domain>/bootstrapSave the output for the next steps.
Note: If the HTTPS certificates are not configured locally, traefik has a default certificate that is used in such cases. To use traefik's default certificate, it is necessary to add -k parameter to the curl command otherwise the request will fail.
List the stack services:
docker stack services knot-cloudRemove the bootstrap service (get the name from the list above, probably will be knot-cloud_boostrap):
docker service rm <bootstrap-service-name>The stage 2 is the last stage, in which the user authentication service and the configuration UI are started. The next sections provide the instructions to configure and deploy them.
Get the authenticator's UUID and token from the bootstrap output and set AUTHENTICATOR_UUID and AUTHENTICATOR_TOKEN variables in knot-cloud-authenticator.env.
KNoT Cloud supports several mail services and is built in such a modular fashion that it is rather trivial to include a new one. Deploying KNoT Cloud without a mail service is also allowed, although not recommended other than for testing purposes. The supported mail services and related environment variables are:
- Disable mail service
MAIL_SERVICE=NONE - Mailgun
Where
MAIL_SERVICE=MAILGUN MAILGUN_DOMAIN=<your_mailgun_domain> MAILGUN_API_KEY=<you_mailgun_api_key>MAILGUN_DOMAINandMAILGUN_API_KEYare your Mailgun's account domain and API key. - AWS SES
Where
MAIL_SERVICE=AWS-SES AWS_REGION=<aws_user_region> AWS_ACCESS_KEY_ID=<aws_user_acess_key_id> AWS_SECRET_ACCESS_KEY=<aws_user_secret_acess_key>AWS_REGION,AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYare your Amazon Web Services' account information. If you are running KNoT Cloud on AWS EC2 that is using roles to grant permissions, it is not necessary to setAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY. The role attached to the EC2 instance must include a policy that allowsses:SendEmailactions at least on the domain used to send the reset e-mail (seeRESET_SENDER_ADDRESSbelow). For more information on AWS SES policies, refer to their documentation.
Set RESET_SENDER_ADDRESS with the e-mail address that will send the reset password e-mails.
If this stack is being deployed on an accessible domain, replaced RESET_URI with http://<your-domain>/reset. This is the reset password address that is going to be sent by e-mail.
This is a required option, but you could fill using a bogus e-mail address if it will not be used or you have set the mail service to NONE.
Deploy the stage 2 services
docker stack deploy -c stage-2.yml knot-cloudAccess KNoT Cloud in your browser at https://www.<your-domain>.