Ask#

Updated: 11/29/2016

Latest Releases:
Ask 0.4.6
Ask Installer 0.0.8

What is Ask?#

Ask lets you easily create embeddable forms, manage submissions, and display galleries of the best responses. It’s fast, flexible, and you control the design and the data.

  • Boost engagement: Editors and journalists can directly tap into the contributor stream to easily solicit, invite and feature user-generated content that compliments the narrative
  • Engage your community: Community members can lend their personal knowledge and experiences for trending stories, improving the quality of the coverage while building a sense of investment among readers
  • Add to other metadata: Once installed and integrated with the Coral Project ecosystem, editors and publishers will gain the power to connect user-generated submissions to other logged-in interactions such as comments, with user opt-in permission

We’ve created a guide on creating effective, targeted questions that attract and engage contributors. You can read it here. #ProTip


1. Setup AWS Instance

2. Set up S3 bucket & IAM User

3. Activate DNS for SSL cert

4. Slack Notifications

5. Configure Ask Environment

6. Run Ask Install

7. Upgrading Your Ask Install

Before You Get Started#

This installation guide is intended for the primary use case of a cloud installation of Ask on Amazon AWS. Ask can be deployed locally onto most cloud platforms.

The install consists of standing up a server, configuring secure terminal access via ssh, creating an S3 bucket for file storage, connecting the server to publicly available DNS for SSL cert generation, downloading the latest Ask installer from GitHub, providing answers for the configuration script and then activating the Ask server which downloads, builds and launches a series of Docker containers for the front-end, MongoDB database, web server, authentication, etc.

Hosting your Ask Install#

Ask can be installed on a local machine or a server. Local installs are generally for evaluation or development purposes. Server installs are no different than local installs except they are on a server that is accessible by others.

Before starting, you will need to:

  • Provision a server
  • Get access to it via ssh

The web url will generally look like this: http://localhost:2020. You may pick any free port you like. If you’re not sure which ports are free, use :2020 as this is rarely taken. Local installs do not support ssl over https.

Operating System#

  • Any version of Linux supported by Docker. +1 for Ubuntu (Recommended method and distro)
  • Ask can run on any Linux Docker container service. Cloud options include AWS, Azure and similar cloud hosting providers
  • MacOS Yosemite 10.10.3 or higher
  • Microsoft Windows is not supported at this time
  • Windows Server Containers 2016 is untested

SSL certificates / HTTPS#

Server installs can use ssl to allow secure https connections but dns needs to be installed first. In order to activate SSL, a domain or subdomain must be mapped to the Ask instance so the webserver portion of Ask (we use Caddy) can request a certificate from Let’s Encrypt.

1. Setup AWS Instance#

  • Option A: Use the Coral Ask AMI here by searching for coral-ask-ami in the Amazon Marketplace

  • Option B: Use your own custom AMI using the following steps:

  1. Select an AWS AMI Image that contains a supported Operating System:

  2. Select Instance Type and then click ‘Next’:

    • t2.medium (Recommended)
  3. Configure Instance Details and then click ‘Next’

    • Number of Instances:
      • 1 (Recommended)
    • Network, Subnet and Auto-Assign Public IP:
      • Ensure the EC2 instance is placed into a VPC network and subnet that match your desired goals for demo/testing/production availability
    • IAM Role:
      • None
    • Leave these items at defaults (Optional)
    • Shutdown behaviour
    • Enable termination protection
    • Monitoring
    • Monitoring
  4. Add storage:

    • Enter ‘10GB’ and then click ‘Next’
  5. Tag Instance (Optional)

  6. Configure Security Group

    You can use an existing security group or create a new one in AWS’s VPC.

    • Networking Tips

      • Limit remote access via ssh/22 to only the necessary IP’s of your office connection which can be found using sites like https://whatismyipaddress.com/

      • If you use a VPN, you can find out what range is covered and enter that in as well

    • We recommend you define access for the following ports:

      Type  Protocol  Port  Source    IP
      SSH   TCP       22    MY IP     YOUR-IP-ADDRESS/32 (example 64.28.114.31/32)
      HTTPS TCP       443   ANYWHERE  0.0.0.0/0
      HTTP  TCP       80    ANYWHERE  0.0.0.0/0
  7. Review your EC2 Instance Settings for the server

  8. Create new key pair or use existing one (You will need this information to ssh into the server) and note the download location

  9. Launch your new AWS EC2 instance!

  10. To ssh into the server, you need to change the permissions on your private key (NAME-YOU-SELECTED-FOR-THE-KEY.pem file) that you downloaded a few steps ago. It may be in your Downloads folder. This file cannot be readable by everyone; if it is, your ssh connection will be refused. Running the unix command ‘chmod’ against the file will resolve it.

    • You can cd to the directory that contains the .pem file
    • Reference its current location but stay in your current directory
    • Move it to a new location
      $ chmod 400 /path/to/your/private-key.pem

    Have questions? Check out the Amazon AWS knowledgebase article Connecting to Your Linux Instance Using SSH

  11. Connect to your newly launched server via SSH using this format:

        $ ssh -i /path/to/your/private-key.pem ubuntu@public-AWS-DNS-NAME
  12. You can check that docker is running by using docker-compose ps

    Note: Make sure you’re using ubuntu for the username to connect if that is the AMI you selected and launched. root may not work.

  13. Once you’re able to successfully connect, run the following command on the remote server to download and install the images, packages, certificates and tools related to Docker. These items will be used as the foundation for your Ask instance:

    $ sudo apt-get -y update && sudo apt-get install apt-transport-https ca-certificates && sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D && echo "deb https://apt.dockerproject.org/repo ubuntu-xenial main" | sudo tee /etc/apt/sources.list.d/docker.list && sudo apt-get -y update && sudo apt-get -y install linux-image-extra-$(uname -r) linux-image-extra-virtual && sudo apt install python-pip && sudo apt-get -y install docker-engine && sudo chown -R $(whoami) /usr/local/bin && curl -L "https://github.com/docker/compose/releases/download/1.8.1/docker-compose-$(uname -s)-$(uname -m)" > /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose
  14. Run this command which will query both docker and docker-compose packages for their location and version:

    $ which docker;docker --version;which docker-compose;docker-compose --version

    Make note of the locations and version in a text file in case you need to troubleshoot your installation. You should get results similar to this:

    /usr/local/bin/docker
    Docker version 1.12.1, build 23cf638
    /usr/local/bin/docker-compose
    docker-compose version 1.8.0, build unknown

2. Set up S3 bucket & IAM User#

New to working with Amazon’s S3 file storage service? Check out this AWS knowledge article S3 buckets - Getting Started with Amazon Simple Storage Service and we have an article in the FAQ section on S3 terminology. Continue through the set up guide once you’ve reviewed these support articles.

  1. From AWS S3 dashboard, create new bucket.

    During the Ask Configuration Tool set up you will be asked to provide: - The name of your S3 bucket - The region the bucket is located in

        Bucket example: YOUR-BUCKET-NAME.s3.amazonaws.com
        Region example: us-east-1
  2. Next, add a bucket policy by clicking on bucket name and then clicking on ‘Properties’ in upper right hand corner.

  3. Click on ‘Permissions’ and select the “Add Bucket Policy” if you have just created the bucket (otherwise the label will say ‘Edit Bucket Policy’)
  4. Copy/Paste the following into the bucket policy box, then select ‘Save’ and ‘Close’.

                    {
            "Version": "2008-10-17",
            "Statement": [
                {
                    "Sid": "AllowPublicRead",
                    "Effect": "Allow",
                    "Principal": {
                        "AWS": "*"
                    },
                    "Action": "s3:GetObject",
                    "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
                }
            ]
        }

    Note: Please ensure your bucket name falls within the AWS Bucket DNS Naming Convention.

  5. Create IAM user with write access to AWS S3 bucket

    • From the AWS IAM dashboard, create a new user, giving the same name as the S3 bucket
    • Make note of the credentials in a secure location and then finish the user set up
    • On the left, click ‘Policies’, then ‘Create policy’ and ‘Create your own policy’ so you can paste in the following and change the bucket name:

                  {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "Stmt1478122637000",
                  "Effect": "Allow",
                  "Action": [
                      "s3:PutObject",
                      "s3:PutObjectAcl",
                      "s3:PutObjectVersionAcl"
                  ],
                  "Resource": [
                      "arn:aws:s3:::YOUR-BUCKET-NAME-HERE"
                  ]
              }
          ]
      }
    • Now click into the user and click the tab ‘Permissions’, then ‘Attach Policy’ and find the one you just created, attaching it to this user.

    • You will need the user ‘Access Key ID’ (Not the Secret Key) during the Ask Installation

3. Activate DNS for SSL cert#

  1. Depending on who your domain registrar is, this process will vary. The end goal is to create an A record for EC2 Instance connecting the server’s Public IP and the domain/subdomain you’ve selected:

    Example DNS Record
    A   ask-stg-docs.coralproject.net   54.193.105.56

    Once you’ve made the changes and verified that the DNS is resolving to the new address (OpenDNS CacheCheck is a reliable way to check for DNS propogation).

    It’s time to test the DNS resolution by reconnecting to the remote server using the new domain/subdomain address. If you’re still connected to the remote server, exit it and reconnect via the DNS address you’ve created:

    Example of ssh connection using a DNS registered subdomain
    $ ssh -i /path/to/your/secret-key.pem ubuntu@ask-stg-docs.coralproject.net

4. Slack Notifications#

Now you can get notifications on Slack when new form submissions come in.

  1. Create a Slack incoming webhook (see: https://api.slack.com/incoming-webhooks)

  2. Run the Ask installer and choose y for Slack integration:

    Do you want form submissions to post to a slack channel?
  3. Input your incoming webhook url:

    What is the slack incoming hook url?:
  4. And finally, enter the channel where you want to receive the notifications:

    What is the slack channel you want notifications posted? (without the #):

5. Ask Configuration Tool#

Back on the remote server, change directories to begin running the Ask Configuration Tool

Run this command to create the coral directory in the /opt/ directory and then drop into it:

$ sudo mkdir /opt/coral/ && cd /opt/coral/

Run this command to download the latest release of Ask, unzip it and change directories into it:

$sudo curl -LOk https://github.com/coralproject/ask-install/releases/download/v0.0.8/ask-install_0.0.8_linux_amd64.tar.gz && sudo tar zxvf ask-install_0.0.8_linux_amd64.tar.gz && cd ask-install_0.0.8_linux_amd64/

From this directory, run the following commands:

  • To ensure the files were unpacked properly

    $ sudo ls -la
  • To Start the Ask Configuration Tool

    $ sudo ./ask-install

Here are the prompts you will recieve during the configuration process:

    **Coral Project ASK Installer**

    ~~ General Configuration ~~

    Do you want to use the stable version of ask?: (y)

    This is where you can specify the host on which the provided server will bind
    to. If you specify the host with a port, it will specifically bind to that port,
    otherwise, port 80, 443 will be bound to

    What's the external hostname of this machine?: (Use DNS name you created. Example ask-stg-docs.coralproject.net)

    Do you want SSL enabled?: (y)

    External URL will be "https://ask-stg-docs.coralproject.net", is that ok?: (y)

    Do you want to enable recaptcha?: (y) WHERE TO FIND THIS?
    Create a captcha id via Google service: [https://www.google.com/recaptcha/admin#list](https://www.google.com/recaptcha/admin#list)

    Create label for easy identification
    Enter DNS domain or subdomain you created earlier (Example

    Do you want to enable Google Analytics?:

    What is the Google Analytics ID?: 
    _YOU NEED TO HAVE ALREADY CREATED A Google Analytics ID and PROPERTY CREATED_

    ~~ Amazon ~~

    Do you want forms uploaded to S3?: (y)

    What's the S3 Bucket we can upload forms?: (enter your bucket url using the virtual-style url: ask-stg-docs.amazonaws.com)

    What's the S3 Region for this bucket?: (example: us-east-1)

    You can find your bucket location in the properties of the bucket where you went to add the policy.

    NOTE: Most buckets are created in the US Standard region which translates to: us-east-1

    What's the AWS_ACCESS_KEY_ID with write access?:

    What's the AWS_ACCESS_KEY associated with this AWS_ACCESS_KEY_ID?:

    Is this bucket hosted in AWS?: (y)

    Auth EXPLAIN THIS IS FOR THE ASK APPLICATION TO SIGN IN

    What's the name for the user account?: WHICH WHAT USER ACCOUNT?


    ~~ Auth ~~

    What's the name for the user account?:

    _YOUR-PREFERRED-USERNAME_

    What's the email address for the user account?:

    _YOUR-PREFERRED-EMAIL-ADDRESS_

    Password

    _YOUR-PREFERRED-PASSWORD_

6. Run Ask installer#

  1. Start the Ask Install

    $ sudo bash setup.sh
  2. Your outupt will look similar to this:

    Pulling service layers:
    
    Pulling cay (coralproject/cay:release)...
    release: Pulling from coralproject/cay
    3690ec4760f9: Pull complete
    e13b170882f4: Pull complete
    6a5d3c1484a0: Pull complete
    f421a9935a76: Pull complete
    aa99a6213a5e: Pull complete
    37e8dfe8d33c: Pull complete
    320469ff2d48: Pull complete
    Digest: sha256:3b4530c303ceedef51f2d21de9bf8593fd11dae2cdd16a2953a22f214fde3971
    Status: Downloaded newer image for coralproject/cay:release
    Pulling auth-mongo (mongo:3.2)...
    3.2: Pulling from library/mongo
    43c265008fae: Pull complete
    679a27ed88fa: Pull complete
    480a2b7cac89: Pull complete
    ab47cdcec495: Pull complete
    9256de55cd57: Pull complete
    4b9dc6db2834: Pull complete
    9c2b45b7a40c: Pull complete
    24f5d27d1e75: Pull complete
    51170f94141d: Pull complete
    Digest: sha256:89ad0ed6321f48107356db1e11984e56614bdee64c3ad8a05484187f276ff705
    Status: Downloaded newer image for mongo:3.2
    Pulling auth (coralproject/coral-auth:release)...
    release: Pulling from coralproject/coral-auth
    43c265008fae: Already exists
    af36d2c7a148: Pull complete
    143e9d501644: Pull complete
    f6a5aab6cd0c: Pull complete
    1e2b64ecebce: Pull complete
    328ff1526764: Pull complete
    c76215a860ef: Pull complete
    214652c77563: Pull complete
    69cd98d02bcc: Pull complete
    b93a19fe5519: Pull complete
    Digest: sha256:1d4a12cdf42bb705afa82ca8e8f553ca62dd1077bb1db1a5521fd92d29a3fccb
    Status: Downloaded newer image for coralproject/coral-auth:release
    Pulling shelf-mongo (mongo:3.2)...
    3.2: Pulling from library/mongo
    Digest: sha256:89ad0ed6321f48107356db1e11984e56614bdee64c3ad8a05484187f276ff705
    Status: Image is up to date for mongo:3.2
    Pulling askd (coralproject/askd:release)...
    release: Pulling from coralproject/askd
    0c7a0ecaa102: Pull complete
    Digest: sha256:76dac36cd8932ff2126b1f37fe2fd6953e89fef1fb02cfed047efb41481d86dc
    Status: Downloaded newer image for coralproject/askd:release
    Pulling elkhorn (coralproject/elkhorn:release)...
    release: Pulling from coralproject/elkhorn
    43c265008fae: Already exists
    af36d2c7a148: Already exists
    143e9d501644: Already exists
    f6a5aab6cd0c: Already exists
    1e2b64ecebce: Already exists
    328ff1526764: Already exists
    d8ec3ca6e46d: Pull complete
    03a50b1af8ce: Pull complete
    45a08e4a4e5b: Pull complete
    9a3d11a196aa: Pull complete
    a2c06c847a68: Pull complete
    071185f1e460: Pull complete
    d9cbe6f0e6cb: Pull complete
    Digest: sha256:f2bc639dc5a2ad4f53c892836583cd7c1fac7fc612d8c4789332e6bf1b591bfc
    Status: Downloaded newer image for coralproject/elkhorn:release
    Pulling caddy (abiosoft/caddy:latest)...
    latest: Pulling from abiosoft/caddy
    c0cb142e4345: Pull complete
    609cd02c9311: Pull complete
    e9712291594a: Pull complete
    7fb56319a17b: Pull complete
    59112d0d06c2: Pull complete
    Digest: sha256:bdc0b59a6a6b88135f6a61343a66870f565966b0080f4dd492447cf651e10ead
    Status: Downloaded newer image for abiosoft/caddy:latest
    Layers pulled.
    
    Creating the services now:
    
    Creating network "askinstall007linuxamd64_back-auth" with the default driver
    Creating network "askinstall007linuxamd64_bastion" with the default driver
    Creating network "askinstall007linuxamd64_back-shelf" with the default driver
    Creating volume "askinstall007linuxamd64_shelf-mongo" with default driver
    Creating volume "askinstall007linuxamd64_auth-mongo" with default driver
    Creating volume "askinstall007linuxamd64_caddy-certs" with default driver
    Creating askinstall007linuxamd64_cay_1
    Creating askinstall007linuxamd64_auth-mongo_1
    Creating askinstall007linuxamd64_shelf-mongo_1
    Creating askinstall007linuxamd64_askd_1
    Creating askinstall007linuxamd64_auth_1
    Creating askinstall007linuxamd64_elkhorn_1
    Creating askinstall007linuxamd64_caddy_1
    
    Services created.
    
    Now creating user:
    
    Created user 879f8fcb-c7a2-49b2-8fd3-1d7e7d1b3611.
    
    User was created.
    
    Please remove this file as it contains the plaintext password.

7. Upgrading Your Ask Install#

  1. Make sure you have the latest version of the Installer: https://github.com/coralproject/ask-install/releases

  2. Run the following commands (NOTE: the -s argument is very important):

    $ sudo ./ask-install -s
    $ sudo  docker-compose pull
    $ sudo  bash setup.sh
    $ sudo  docker-compose up -d

Software Versions#

Docker#

Docker 1.12.1 or later is required.

Please make sure that the docker install is a stable release as we have encountered problems with experimental Docker releases.

Docker Compose#

Docker Compose 1.8.1 or later is required.

Visit the Docker Compose website for the latest release.

FAQ & Troubleshooting#

What is AWS S3 and why would you want to activate it?

Ask publishes forms and gallery embeds to static files. This improves load times, allows for greater scale and availability. If you don’t expect many thousands of forms requests per day, it is probably best to not use S3. By default Ask will publish files to and serve them from the same server it runs on.

If you want to publish to S3, please create a bucket for Ask and have the following pieces of info at hand during the installation:

  • S3 bucket name
  • S3 public key
  • S3 secret key

For very large or international sites, you may want to consider using a CDN caching services in front of your S3 bucket such as Amazon CloudFront, Cloud Flare or similar.

SSL Certificates / HTTPS

Will you be hosting Ask over https? If you’re ok with http or you’re installing a local machine (as opposed to a server that’s accessible by others), you may proceed to the next question.

If you want to use https, you will need to go to your DNS provider and set up the domain to point to your new server before you run the install script. This is required because Ask contains an automated mechanism for acquiring a secure certification (https://github.com/mholt/caddy) and keeping it up to date. The server must be reach it using a publicly accessible url such as https://your.domain.com in order for this to happen.

If you’d like to use another platform to host your files, let us know. We can work together to build it as an option into the Coral Platform. Send a mesage to jeff@mozillafoundation.org.

Spam Reduction with reCaptcha

Do you want reCAPTCHA enabled?

Ask Forms can be protected from bots submitting false entries via reCAPTCHA. You can learn more about it here: https://www.google.com/recaptcha/intro/index.html.

If you want to use reCAPTCHA, you need to have signed up for an account and have the keys ready as they will be needed during the Ask install process.

We have encountered errors when installing into symlinked folders

Cannot connect to the Docker daemon. Is the docker daemon running on this host?

This error can occur if you need to run the docker command with sudo such as:

$ sudo docker ps