Setting up a ToolTwist On Demand server - tooltwist/documentation GitHub Wiki

PLEASE NOTE: WE DON'T USE THIS ANY MORE

A ToolTwist On-Demand server allows new instances of ToolTwist to be fired up at will.

A Docker server is used, which fires up Docker containers to run the individual ToolTwist instances. Nginx is used as a proxy server to route requests to the appropriate Docker container.

At the time of writing this is only being used to run instances of the Designer.

By default, this server will create a new instance any time an unrecognised URL is called. Care must be taken therefore with who knows the actual URL in use. This automatic-spawning can be disabled, as discussed below.

Configuring the Server

Create a Server

1. Start a new Digital Ocean Droplet, for the 'Docker' image.

2. Before proceeding, you need a domain name for this server, and it's various subdomains. For the rest of this tutorial we'll use the name 'myhost.com'.

3. Set up DNS entries to this new server. The following entires set up subdomains like fred.myhost.com.

    HOST NAME       IP ADDRESS/ URL      RECORD TYPE  
    @               128.199.237.125      A (address)  
    www             tooltwist.website.   CNAME (Alias)  
    *               tooltwist.website.   CNAME (Alias)  
   

4. Log on as root. We use root for everything on the Docker host as it avoids Docker permission problems. Note that the web servers themselves run safely inside Docker containers, so using root here this provides minimum security risk.

5. Install git

    $ apt-get install git
   

6. Create a directory for container files.

   $ mkdir /root/volumes

Wait for the DNS entry to propagate

1. You may need to wait for the DNS entries set above to propagate around the Internet.

    $ ping www.myhost.com  
    PING parkingpage.namecheap.com (199.59.166.109) 56(84) bytes of data.
   

If it shows the correct IP address you are ready to continue...

Start and test the proxy

1. Download the scripts

    $ cd /root  
    $ git clone https://github.com/tooltwist/tooltwist-spawner.git
   

2. Start the proxy

    $ cd tooltwist-spawner  
    $ ./start-proxy.sh
   

If you now point your browser to http://**www**.myhost.com, you should see an error (503 Service Temporarily Unavailable).

1. Start the test container:

    $ ./start-hello.sh
   

If you run docker ps you should see containers for hello and proxy.

If you refresh your browser you should now be able to see a web page (Hello world! My hostname is ...)

docker-designer

1. Prepare a docker image for ToolTwist:

   $ cd /root
   $ git clone https://github.com/tooltwist/docker-designer.git
   $ cd docker-designer
   $ cp env.sh-digitalocean env.sh
   $ ./build.sh

2. Check the image

   $ ./start.sh junk1

If you got to http://junk1.myhost.com/ttsvr/login you will initially get an error (502 Bad Gateway). If you wait a minute or two and refresh you should see the ToolTwist login page. You can check the container's startup using this command:

  $ docker logs designer-junk1

You can check the output from Tomcat using:

  $ tail -f tail -f /root/volumes/logs-junk1/tooltwist.out

This should start the image - check it is running in Docker:

  $ 

tooltwist-spawner

This is a Docker container that receives all unmapped requests to the server. For example somejunk.fickle.ninja. It peels off the subdomain name, and fires up a new docker-designer container to handle the requests.

1. Now build and run the Docker image for the spawner:

    $ cp env.sh-linux env.sh  
    $ vi env.sh     (set the HOSTNAME to the DNS domain you created previously)  
    $ ./build.sh  
    $ ./start-spawner.sh  
   

If you go to an unknown page such as http://whatever.myhost.com you should receive details of the new container being started:

    This is the index page.
    Domain is whatever.myhost.com 
    Starting server for user whatever.

If you refresh the page immediately you will probably get a 502 Bad Gateway error, but after about a minute the server should be started and you will see the ToolTwist login screen.

Locking down the Server

If you wish to prevent new subdomains from being fired up on demand, simply stop the spawner container.

$ docker stop spawner

Volumes attached to Docker images

The Docker images for the ToolTwist Designer are started with an external volume used to store parts of the filesystem that need to be persisted across a server restart. For example /volumes/user-philcal contains the directory where the ToolTwist CLI is run, and /volumes/logs-philcal is mapped to ~/site-conf/logs inside the docker container.

Supporting a Different Domain Name

If you wish to have a different domain name be routed to a Docker container on this server, you can do it by copying and modifying the start-hello.sh script. The VIRTUAL_HOST environment variable passed to Docker should be the full domain name requests to the server will use.

If you wish to use a Docker image saved on Dockerhub, this name should replace tutum/hello-world.

--