Quickstart

A quickstart tutorial how to install Civilian, create and run a new application. Can be completed in a couple of minutes (depending on fitness level).

1. Check system requirements

In order to follow this tutorial you need:

a Java JDK (8+)
Apache Ant (1.6.0+)
Apache Ivy

Please make sure that you can run java and ant from a console prompt.
If you don't have Apache Ivy installed, download it from Apache, unpack the downloaded zip file wherever you want, and copy the ivy jar file into your ant lib directory (ANT_HOME/lib).

2. Download Civilian.jar

Download the latest civilian-3.0.jar and store it into a local directory.

3. Run the scaffold tool to create a new application

Civilian contains a scaffold tool to create a new application.
To run the tool open a console prompt in the directory where you stored the Civilian jar file.
Choose a project directory into which the scaffold tool will write the application files.
Lets suppose you chose /temp/civilian/quickstart. Now run the scaffold tool

java -jar civilian-3.0.jar -v /temp/civilian/quickstart Qs

Some messages are printed, but just confirm that the last line says done.

4. Build the new application

Navigate to the directory /temp/civilian/quickstart created in step 3. You will find an ant build file, a src, bin and web directory containing source code and other resources of the scaffolded application.
Open a console prompt in that directory.

First we use Ant and Ivy to download needed runtime libraries which are not distributed with Civilian. Run:

ant resolve

You will see a lot of Ivy messages. If the task runs without errors, the lib subdirectory should now contain Gson, Slf4J and Jetty libaries. Gson and Slf4j are required by Civilian, Jetty is just used as the simplest way to run the scaffolded webapp.

Now compile the application:

ant compile

5. Run the application

In this step we run the application.

ant jetty

Jetty has started up (of course Civilian also runs with any other servlet 3.0+ container) – now take a look at the application: http://localhost:8080/.
Minimal as it is.
Or open http://localhost:8080/civadmin which is Civilians admin application.

6. Development preview

In the last step we demonstrate class reloading, as preview on Civilians rapid development support.
Browse to http://localhost:8080/users.
Now open the class src/com/qs/web/users/IndexController.java (which actually produces this exciting page) in an editor and modify the render-method:

@Get @Produces("text/html") public void render() throws Exception
{
    getResponse().write("list users...changed");
}

or something like that. Save and then recompile with ant compile in a new console, but don't stop the running Jetty. Go back to the browser and hit refresh. You will see the changed output. Magic!

Thanks for completing this tutorial. You may now want to explore the anatomy of the generated application, or simple start reading the documentation.