4. Getting Started

We're going to assume that you have all the dependencies needed and already forked the repository on Github. If you haven't, follow these steps to do so.

Git clone

Clone the repository you just forked on your account. To do so, go to the repository, and copy the clone link, which should look like something like that:

Then, in your terminal, or in Git Bash, navigate to your working directory (where you want the project to be saved) and clone the repository inside it by typing:

git clone git@github.com:your_username/Instant-Answers.git

You should now have a local copy of the Instant Answers project.

Running Instant Answers

Running Qwant's Instant Answers means that you'll have a local server running and serving you the data calculated and processed by the different modules. You will need to run it to test your changes.

Thankfully, running the server is pretty straightforward, as Docker will handle everything for you. Docker will create the needed containers, install all the dependencies the project needs on them and will run it.

In a terminal, at the root of the project (for me it's ~/work/Github/Instant-Answers), type in:

bin/start

This, thanks to the docker-compose.yml file, will download and install every image needed by the Docker containers to run the project properly (debian, node, redis, sass...). It will then automatically install all the npm dependencies, launch the Grunt tasks, and start the server. It will take some time the first time, but will be much faster the next time as Docker won't have to download and install everything again, unless told otherwise.

After a while, you should see something like:

instant-answers_1  |     Running "nodemon:dev" (nodemon) task
instant-answers_1  |     Running "nodemon:front" (nodemon) task
instant-answers_1  |     [nodemon] 1.18.4
instant-answers_1  |     [nodemon] to restart at any time, enter `rs`
instant-answers_1  |     [nodemon] watching: *.*
instant-answers_1  |     [nodemon] starting `node bin/www`
instant-answers_1  |     Running "watch" task
instant-answers_1  |     Waiting...
instant-answers_1  |     [nodemon] 1.18.4
instant-answers_1  |     [nodemon] to restart at any time, enter `rs`
instant-answers_1  |     [nodemon] watching: *.*
instant-answers_1  |     [nodemon] starting `node front/bin/www`
instant-answers_1  |     info: Starting IA-Core v3.1.1 server...
instant-answers_1  |     
instant-answers_1  |     info: Loading modules...
instant-answers_1  |     info: calculator loaded
instant-answers_1  |     info: currency_converter loaded
instant-answers_1  |     info: current_time loaded
instant-answers_1  |     info: current_week loaded
instant-answers_1  |     info: encryption loaded
instant-answers_1  |     info: hello_world loaded
instant-answers_1  |     info: Front sandbox started, listening on port 3030 -> http://localhost:3030/
instant-answers_1  |     info: npm loaded
instant-answers_1  |     info: timer loaded
instant-answers_1  |     info: unit_converter loaded
instant-answers_1  |     info: weather not loaded (excluded) module=ia module loader
instant-answers_1  |     info: IA Order: 0: calculator, 20: currency_converter, 30: encryption, 60: npm, 80: unit_converter, 82: current_time, 103: current_week, no order: hello_world, no order: timer
instant-answers_1  |     info: Server started, listening on port 3002 -> http://localhost:3002/

As you can see, Docker installed everything it needed, and has launched both the server (node bin/www) and the front sandbox (node front/bin/www).

Server: http://localhost:3002 Front sandbox/demo: http://localhost:3030

The front sandbox is running and listening to the port 3030. If you open your browser and go to http://localhost:3030, you should see a copy of Qwant.com's interface. Since you didn't give any query, it redirected you to the hello world IA as a demonstration. Try typing a query in the search bar (examples: 2*2, npm grunt, sha256 no tracking).

The server is running and is listening to the port 3002. If you open your browser and go to http://localhost:3002, you should see an error saying "No query given":

http://localhost:3002/

{  
   "error":200,
   "message":"No query given"
}

This is normal. The server is waiting for a query to handle. To test your IA, you can directly type in your query in the URL, like this:

http://localhost:3002/?q=sha256+no+tracking

This should print an answer like this one:

http://localhost:3002/?q=sha256+no+tracking

{
    "runtime": "nodejs",
    "template_name": "encryption",
    "display_name": "hachage",
    "images_path": "ia/img/",
    "data": {
        "result": "87c9b69c9e6b164a2ab9350dfebf4e3a5814e5abb8dcb6c5f9c7df3191b835c0",
        "stringToHash": "no tracking",
        "hash": "SHA256"
    },
    "query": "sha256 no tracking",
    "status": "success",
    "cacheExpirationTime": 200,
    "files": [
        {
            "url": "ia/template/fr_fr/encryption.js?deef78e5a4f7bc21f549c05b7038f8508caa9631",
            "type": "template"
        }
    ]
}

As you can see, the IA server detected that we were looking for the encryption module, because one of its keywords, sha256, was detected in the query.

The response contains several information, such as where some public files should be (for proper display), the status of the query, and of course the result of the query ("data" field).

There are other useful information in the response, but we will cover them later.

Watch

A watcher is included in this project. A watcher is a service that watches for changes in a file in order to fire some tasks. In our case, each change to a file (.js, .dot, .scss) will fire the correct grunt task, allowing us to keep developing and see our changes in action without having to restart the server or grunt entirely.

Every time you make a change in a watched file, you will see your terminal react and do the appropriate actions.

How do I create my own IA now?

To create your own IA, we've added a tool to our project that will generate every file you will need, at the right place. To use this tool, type in:

bin/new

and follow the steps. A bunch of files will be generated. This is where the fun really starts!

Dynamic resolution

In order to avoid typing bin/ before all the commands, we recommend adding bin/ to your PATH:

export PATH="bin:$PATH"

You can then simply use:

start

or

new

For the remaining of this documentation, we will assume you have bin/ in your PATH.