Please note that Sincerity is still under development and that this documentation is incomplete.
Skeletons
You've most likely come to Sincerity for the skeletons: they provide the easiest way to get started with all kinds of frameworks, servers and libraries, while Sincerity lets you easily add more features, more libraries and more languages as your project grows.
Nexus Skeleton
Sonatype's Nexus repository manager is a recommended companion for Sincerity. At its most basic, it provides you with a proxy for accessing remote repositories, such as the Three Crickets repository in which many Sincerity packages are stored. Accessing repositories via a proxy provides you with much better performance and reliability. Nexus is a very powerful tool, and learning how to use it well will can go a long way towards improving your Sincerity experience.
With Sincerity, it's a piece of cake to install a working Nexus instance:
sincerity add nexus : install
Give this a minute or two: Nexus has a lot of dependencies, though most are tiny.
To start the server:
sincerity start jetty
The default port is 8080, so point your browser to http://localhost:8080 to see your new Nexus repository manager. The default user is "admin" with password "admin123". You probably want to log in and change that password. Nexus provides a rich web-based interface and includes excellent documentation.
Note that the Nexus skeleton relies on the standard Jetty servlet skeleton, to which you can indeed install other "contexts" (web applications).
Fleshing Out
You may want to change the default port from 8080, which you can do by editing "/server/connectors/default.js".
Otherwise, the default configuration should be quite sensible. It includes support for the standard repositories used by Sincerity, in addition to the Nexus defaults. Logging has also been configured to adhere to Sincerity's container structure, so that logs will appear under "/logs/". Note that Nexus itself will not use Sincerity's logging plugin, but you can configure Nexus logging right in the user interface.
Extras
sincerity add logging : add service : install
Note that the Nexus application uses its own logging implementation, which must be configured internally. However, the logging plugin will be put to good use by the containing Jetty server.
The following command will install a Nexus repository with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add nexus : add logging : add service : install : service jetty start
To stop it:
sincerity use mycontainer : service jetty stop
Solr Skeleton
Apache Solr is a popular distributed textual search platform. It runs on the JVM and relies on the excellent Lucene library for indexing and searching, but is accessed via simple network APIs, making it perfect for distributed deployments and heavy loads. Client libraries are available for many platforms, and are even integrated into the backends of many web development frameworks, such as Django and Ruby on Rails.
With Sincerity, it's a piece of cake to install a working Solr instance:
sincerity add solr : install
To start the server:
sincerity start jetty
The default port is 8080, so point your browser to http://localhost:8080/solr/admin/ to see the main Solr administration page.
Fleshing Out
The skeleton comes with the example configuration supplied with the official Solr distribution, and should serve as a good starting point for the majority of project. The configuration is available under "/configuration/solr/conf/", and indexing and other data is stored in "/data/solr/".
Solr is very configurable, both in terms of performance fine-tuning and language analysis and indexing. It also enjoys a range of useful plugins. See the official site for more information on fleshing out your skeleton.
Extras
The logging plugin is strongly recommended. To install it:
sincerity add service : install
Note that the logging plugin is already included in the skeleton, because Solr relies on SLF4J.
The following command will install a Solr server with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add solr : add service : install : service jetty start
To stop it:
sincerity use mycontainer : service jetty stop
Hadoop Skeleton
Apache Hadoop is a powerful platform for distributed computing, well known for its scalable distributed filesystem and popular map-reduce module. It provides the underlying infrastructure for several data storage and analysis platforms, such as Cassandra, HBase, Hive and Pig.
Hadoop runs best on Linux, where it relies on native libraries. This skeleton detects the underlying architecture and downloads the necessary native libraries on-demand.
With Sincerity, it's a piece of cake to install a working Hadoop instance. Note that we need to format the node first:
sincerity add hadoop : install : hadoop namenode -format
(Note that the "namenode -format" command exits the JVM when done, so you cannot chain more commands after it.)
Then, to start the node:
sincerity hadoop start
If this is the only node in your Hadoop cluster, you will need to wait about 30 seconds for the services to fully initialize. To test copying files to and from the Hadoop filesystem:
sincerity hadoop fs -put myfile.txt test.txt sincerity hadoop fs -get test.txt test.txt
To stop the node:
sincerity hadoop stop
To see the status of the node services:
sincerity hadoop status
Note that Hadoop uses the logging plugin to manage the node services.
Fleshing Out
The skeleton comes with a plugin that supports the full list of Hadoop commands, and additionally supports "start", "stop" and "status" to manage the services.
All logs are under "/logs/", and the data is stored in "/data/".
To configure your instance, see "/configuration/hadoop/". The default configuration is based on that of the official Hadoop distribution on ports 8000 (name node) and 8001 (job tracker). The logging configuration is based on the logging plugin, but its essential setup has likewise been copied over from the official distribution.
OrientDB Skeleton
OrientDB is a powerful document- and graph-oriented ("NoSQL") database server designed for scalability. As a graph database, it supports the entire Tinkerpop stack, including the Gremlin graph traversal language, allowing you to easily port your application between different database implementations. For users needing features from traditional RDBMS, OrientDB also supports SQL and allows enforcing schemas on your collections.
If you're interested in a more traditional RDBMS, check out Sincerity's H2 skeleton.
The Sincerity OrientDB skeleton makes it easy to set up and run a single OrientDB instance, which can run on its own or as a node in a multi-master cluster. To install an OrientDB instance:
sincerity add orientdb : install
To start the server:
sincerity start orientdb
The default web port is 2480, so point your browser to http://localhost:2480/studio/ to see the OrientDB Studio application.
To start the console:
sincerity console
In the console, to connect to the demo "tinkerpop" database:
orientdb> connect remote:localhost/tinkerpop admin admin orientdb> gremlin g.V[1]
Fleshing Out
The OrientDB plugin also supports a "gremlin" command to get a pure Gremlin console, though note you can also run Gremlin code in the general OrientDB console by prefixing it with the "gremlin" command.
To configure your instance, start with "/configuration/orientdb/server.conf" (XML). The default "server.conf" also references "database.conf" (JSON) and "hazelcast.conf" (XML).
Additionally, "properties.conf" (properties sheet) can be used to set JVM system properties used by OrientDB.
Databases will be stored in the "/databases/" directory in your Sincerity container.
Extras
sincerity add logging : add service : install
The following command will install an OrientDB node with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add orientdb : add logging : add service : install : service orientdb start
To stop it:
sincerity use mycontainer : service orientdb stop
H2 Skeleton
H2 is a lightweight-yet-powerful relational database management system (RDBMS). It can run both as a standalone server (supporting a PostgreSQL compatibility mode), or embedded in your JVM program.
If you're interested in non-relational ("NoSQL") databases, check out Sincerity's OrientDB skeleton.
The Sincerity H2 skeleton is specifically designed to make it easy to run H2 in standalone server mode. To install an H2 instance:
sincerity add h2 : install
To start the server:
sincerity start h2
The default web port is 8082, so point your browser to http://localhost:8082/ to see the H2 Console application. Note that the web console application is useful not just for H2: it be used to connect to any JDBC URI, as long as you have the JDBC driver installed in your Sincerity container.
Fleshing Out
The H2 plugin supports all the tools that come with H2. You can use "sincerity help" to get a list of them. For example, to create a cluster:
sincerity create-cluster \ -urlSource jdbc:h2:tcp://localhost:9101/test \ -urlTarget jdbc:h2:tcp://localhost:9102/test \ -user sa \ -serverList localhost:9101,localhost:9102
To configure your server, see "/configuration/h2/server.conf". Lines that are not empty and do not begin with "#" will be added as command line arguments to the "server" tool. In fact, you can create ".conf" files for all the H2 tools if you wish to set default command arguments for them. For example, "create-cluster.conf".
By default, databases will be stored in the "/databases/" directory in your Sincerity container. However, note that H2's JDBC URI allows you to access database stored anywhere in the filesystem. If this is a security concern, you may want to consider running the H2 server in a locked-down operating system user.
Extras
sincerity add logging : add service : install
The following command will install an H2 database server with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add h2 : add logging : add service : install : service h2 start
To stop it:
sincerity use mycontainer : service h2 stop
Jetty Web Server Skeleton
Need a web server for static files? No problem:
sincerity add jetty.web : install
Jetty is a very robust, modular web server with excellent asynchronous performance, and lots of features and extensions. With this skeleton we've provided you with the lightweight, bare minimum dependencies to serve just static files for a single web site.
To start you server:
sincerity start jetty
The default port is 8080, so point your browser to http://localhost:8080 to see the default welcoming page.
Jetty allows for much more sophistication than just serving a single web site, and for that we've provided a separate skeleton: "jetty.servlet". That skeleton supports multiple "contexts" under the server, as well as configuration of connectors, and of course servlets and web applications packaged as WAR files.
Additionally, Jetty is a recommended connector for Restlet. It's available as a skeleton add-on, "restlet.jetty".
The Jetty skeletons use Jetty 9.3, which requires a JVM of at least version 8.
Fleshing Out
Just put your files under the container's "/web/" directory, using the usual rules for web servers: URLs are mapped to file paths under "/web/", and directory URLs are mapped to "index.html" files in that directory. MIME types are automatically guessed according to the common filename extensions.
You can configure the server by editing "/configuration/jetty/default.js". For example, you can change the port, enable SSL, and also HTTP/2. Note that support for SPDY must be added as an "extra" (see below).
For SSL, the example comes with a self-signed key stored in a Java KeyStore (JKS) at "/configuration/jetty/jetty.jks". You should use it only for testing! Otherwise, you will want to create or import your own key using the "keytool" utility that is bundled with most JDKs. Here's how to create a new, unique key:
keytool -keystore jetty.jks -alias jetty -genkey -keyalg RSA
Such self-created keys are useful for controlled intranet environments, in which you can provide clients with the public key, but for Internet applications you will likely want a key created by one of the "certificate authorities" trusted by most web browsers. Some of these certificate authorities may conveniently let you download a key in JKS format. Otherwise, if they support PKCS12 format, you can use keytool (only JVM version 6 and later) to convert PKCS12 to JKS. For example:
keytool -importkeystore -srcstoretype PKCS12 -srckeystore mysite.pkcs12 -destkeystore jetty.jks
If your certificate authority won't even let you download PKCS12 file, you can create one from your ".key" and ".crt" (or ".pem") files using OpenSSL:
openssl pkcs12 -inkey /path/mykey.key -in /path/mykey.crt -export -out mysite.pkcs12
(Note that in this case you must give your new PKCS12 a non-empty password, or else keytool will fail with an unhelpful error message.)
Extras
sincerity add logging : add service : install
It is also possible to add HTTP/2 support: this protocol, supported by many web browsers, can improve the user experience as well as reduce server load when using "https".
To install support for HTTP/2, as well as the required ALPN support:
sincerity add jetty.http2 : install
To enable ALPN, you need to specify your "alpn-boot.jar" in the JVM_BOOT_LIBRARIES environment variable, for example:
JVM_BOOT_LIBRARIES=/path/to/mycontainer/libraries/jars/org.mortbay.jetty.alpn/alpn-boot/8.1.3/alpn-boot.jar \ sincerity : start jetty
It's a bit awkward, but necessary due to the way ALPN is securely implemented in the JVM.
The following command will install a web server with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add jetty.web : add logging : add service : install : service jetty start
To stop it:
sincerity use mycontainer : service jetty stop
Jetty Servlet/JSP Skeleton
Servlets let you generate dynamic content for a web site, usually using the Java language. There is a very large ecosystem of free servlets out there, including complete frameworks, that can help you develop dynamic applications.
To install a bare servlet skeleton, based on Jetty:
sincerity add jetty.servlet : install
sincerity start jetty
The default port is 8080, so point your browser to http://localhost:8080. But, you won't see anything yet: this is a bare skeleton waiting for you to add your application to it. You might want to start by installing "jetty.servlet.example" first.
Note that if you only intend to install Jetty as a simple web server for static files, then you can use a simpler skeleton: "jetty.web".
As useful as servlets are, we recommend you take a look at the Restlet skeleton if you want to build a dynamic web application in Java. And Restlet can use Jetty as its underlying connector.
And why stop there? Prudence builds on Restlet, letting you do all of that and more with your choice of JavaScript, Python, Ruby, PHP, Lua, Groovy or Clojure. (Disclosure: Prudence has also been created by Three Crickets.)
The Jetty skeletons use Jetty 9.3, which requires a JVM of at least version 8.
Fleshing Out
Jetty's official distribution (which doesn't rely on Sincerity… yet) is a perfect example of why Sincerity needs to exist. "Official" Jetty configuration is a morass of XML files that effectively duplicate what a lightweight scripting language, like JavaScript does far more comprehensibly and with far greater power. If you're switching from "official" Jetty, then you're in for a treat, as well as a sigh of relief.
Configuration is handled similarly to the Jetty web server skeleton: in the same way, you can add SSL and SPDY support.
Though Jetty can use the logging plugin (see below), it also supports its own internal logging mechanism for the web (NCSA-style) log. To configure it, see "/server/services/web-log.js". By default, these logs will appear under the "/logs/web/" directory, and will be named according to the date.
Extras
Two add-ons are available: "jetty.servlet.jsp" adds support for JSP (JavaServer Pages), and "jetty.servlet.jmx" adds JMX support to your Jetty server, allowing you to manage it via VisualVM or JConsole. To install both add-ons:
sincerity add jetty.servlet.jsp : add jetty.servlet.jmx : install
(You can test JSP support in the example WAR below, at http://localhost:8080/test/jsp/.)
It is also possible to add SPDY support: this protocol, supported by many web browsers, can improve the user experience as well as reduce server load when using "https". For instructions, see the Jetty web server skeleton.
A nice example of a Jetty server with multiple contexts is also provided, which includes a static web server, a servlet container, and a web application installed as a WAR file:
sincerity add jetty.servlet.example : install
(You can install this on its own, and it will pull in the basic skeleton as a dependency.)
The example "/server/contexts/servlet-example/" is the most elaborate: it shows you how you can drop in Java source code for your servlets and have them compiled as the server starts.
sincerity add logging : add service : install
The following command will install the servlet examples with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add jetty.servlet.example : add logging : add service : install : service jetty start
To stop it:
sincerity use mycontainer : service jetty stop
Restlet Skeleton
The Restlet library ("Restlet" is a registered trademark of Restlet S.A.S.) lets you dynamically generate web content, but it goes beyond just responding to client requests: it lets you map RESTful resources to URIs, while handling all the tricky HTTP mechanics involved (content negotiation, conditional HTTP) and providing full, rich abstractions for routing, filtering and data presentation.
To install the minimal skeleton:
sincerity add restlet : install
To start your Restlet component and its servers:
sincerity start restlet
The default port is 8080, so point your browser to http://localhost:8080.
Restlet, on its own, requires you to code in Java, but Prudence builds on Restlet, letting you do all of the above with your choice of JavaScript, Python, Ruby, PHP, Lua, Groovy or Clojure. (Disclosure: Prudence has also been created by Three Crickets.)
Fleshing Out
While Restlet requires you to write your resources in Java, there is no reason for your bootstrapping code—the code that assembles your component, servers, clients, hosts and routes—to be so rigid. The API for boostrapping your component is simple and elegant enough, but without Sincerity you would have to likely have to write it in Java, or implement your own bootstrapping mechanism or use a DSL.
JavaScript, Sincerity's natural language, provides a lightweight solution, and one that does not require you to recompile anything when all you want to change is your configuration. Of course, once your component is up and running, JavaScript plays no more role. We mention that in case you're worried about performance, though you shouldn't be: the language engine is likely not the source of any bottlenecks in your application's live performance.
The skeleton follows the network structure of Restlet, which in turn closely adheres to Roy Fielding's original terminology for Representational State Transfer (REST):
The "/component/" directory is the basis for your REST component.
Under "/component/servers/" you can create files for HTTP servers bound to your component. See the API documentation. The default is a single HTTP server is created on port 8080, but you can create additional servers. The technology used for the servers is called a "connector," and is pluggable in Restlet. Connectors cannot be selected by API calls; rather, they are installed automatically if they are discovered in the classpath. By default, the Sincerity skeleton for Restlet relies on Restlet's internal connector, but it is not recommended for production applications. See "Extras" on how to install other connectors.
A quick and easy way to change the port for the default server is to set the environment variable is "RESTLET_PORT" (or the "restlet.port" JVM property):
RESTLET_PORT=80 sincerity start restlet
Under "/component/hosts/" you can create files for virtual hosts. See the API documentation. The default host has no filters, meaning that all requests from all servers will be routed to it. If you need several virtual hosts, you will want to make the default host less inclusive, or do away with a default host entirely. (The default host is merely a Restlet convenience and is not required for a component.) Applications can be attached to one or more hosts (see below).
Under "/component/clients/" you can create files for clients supported by your component. See the API documentation. As with servers, client technologies are "connectors" installed on the classpath. Each connector handles a specific URI protocol, such as "http:", "https:" and "file:". The skeleton defines no clients by default, but you can create files here for each client you need. Install the Restlet example to see usage of a "file:" client. (The "file:" client is required internally by the Restlet Directory resource.) Note that the Restlet internal connector can handle "http:", but not "https:". To add support for "https:", you can install the Apache HttpClient connector.
The "/component/services/" is used to configure Restlet services, such as ConnegService, TunnelService, EncoderService, etc., but can be used for any additional work to be done before applications are configured. By default only the LogService is configured.
Finally, "/component/applications/" is where you can create your Restlet applications. See the API documentation. Though you can attach applications directly to your component, it is recommended that you attach them to virtual hosts, even if it's just the default host, as it allows you more routing flexibility. Also, though there is no requirement to do so, most Restlet applications will probably have a Router as their inbound root. It is crucial that you understand how routing works in Restlet: from server, through host, through application, through router, and finally to your RESTful resources. Please refer to the Restlet documentation for full details. Note that the skeleton does not include any application by default, but one is available for you to install.
It may be useful during development to start only a few select applications. This can be done by providing the application directory names you wish to start as arguments to the "start restlet" command:
sincerity start restlet restlet-example myapp
Alternatively, you can set the "RESTLET_APPLICATIONS" environment variable (or the "restlet.applications" JVM property) to a comma-separated list of application directory names:
RESTLET_APPLICATIONS=restlet-example,myapp sincerity start restlet
Extras
A simple example Restlet application, with a custom resource as well as static content:
sincerity add restlet.example : install
(You can install this on its own, and it will pull in the basic skeleton as a dependency.)
The example at "/component/applications/example/" shows you how you can drop in Java source code for your resources and have it compiled automatically.
The skeleton does not install any connectors by default, relying instead on the default Restlet connectors. To install the Jetty server connector, you have the choice of either Jetty 9.3 (requires JVM 8) or Jetty 9.2 (requires JVM 7). For 9.3:
sincerity add restlet.jetty : install
For 9.2:
sincerity add restlet.jetty.legacy : install
It is possible to add HTTP/2 support to Jetty 9.3: this protocol, supported by many web browsers, can improve the user experience as well as reduce server load when using "https". For instructions, see the Jetty web server skeleton.
To install the Apache HttpClient connector:
sincerity add restlet.httpclient : install
Other shortcuts include "restlet.simple" (the Simple Framework server connector).
sincerity add restlet.logging : add service : install
(Note that "restlet.logging" is used here in preference over Sincerity's "logging" plugin. The former depends on the latter, but adds a Restlet library that provides a direct chute to SLF4J, which is more efficient than bridging.)
The following command will install the Restlet example with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add restlet.example : add restlet.jetty : add restlet.logging : add service : install : service restlet start
To stop it:
sincerity use mycontainer : service restlet stop
Felix Skeleton
Apache Felix is flexible, straightforward OSGi (R4) container.
To install:
sincerity add felix : install
To start the Gogo console:
sincerity felix
(You can also use "sincerity gogo" instead.) As an example, let's install the web console via Gogo:
install http://archive.apache.org/dist/felix/org.apache.felix.http.jetty-2.2.0.jar start 5 install http://archive.apache.org/dist/felix/org.apache.felix.webconsole-3.1.8.jar start 6
In this example you may need to change the IDs in the "start" command to match the bundle IDs that Gogo reports. Then, point your browser to http://localhost:8080/system/console/. The default user is "admin" with password "admin".
Prudence Skeleton
Prudence is a platform on which you can build scalable web frontends and network services. It lets you write your server-side code in JavaScript, Python, Ruby, PHP, Lua, Groovy or Clojure. Though minimalistic, Prudence addresses real-world, practical web development needs, from virtual hosting and URI rewriting to state-of-the-art server- and client-side caching. Your applications can support rich clients (AJAX), thin clients (pure HTML), and happy mixes between the two.
Prudence is distributed exclusively as a Sincerity skeleton with a large collection of tightly integrated add-ons. It is an extension of the Restlet skeleton, so the documentation there applies here. It is, in turn, the underlying platform for Diligence.
Since version 2.0, Prudence is designed from the ground-up around Sincerity, and such provides the primary example for how Sincerity can reform product distribution.
Historically, it was actually the other way around. Sincerity was designed by Three Crickets precisely in order to make Prudence 2.0 sanely modular, building on many lessons learned while deploying Prudence 1.0 and 1.1. It was clear during development that there was nothing in the proposed solution that was specific to Prudence. And so Sincerity was born as a generic tool useful for many JVM projects.
Quick start to see the Prudence example:
sincerity add prudence.example : install : start prudence
And then browse to http://localhost:8080/.
Diligence Skeleton
Diligence lets you develop scalable data-driven web applications in server-side JavaScript, using MongoDB as its data provider and Prudence as its RESTful base. It features strong integration with client-side "AJAX," notably Ext JS and Sencha Touch, and clean-room integration with Facebook, Twitter, Google, etc. Services include a scalable email notification system, robust sitemap generation (with special support for very large sites), authentication and authorization, and support for several markup languages.
Diligence is distributed exclusively as a Sincerity skeleton. It is an extension of the Prudence skeleton and the Restlet skeleton, so the documentation there applies here.
(Disclosure: Like Sincerity and Prudence, Diligence is developed by Three Crickets. The three products together form a powerful web application stack on top of the JVM.)
Quick start to see the Diligence example:
sincerity add diligence.example : install : start prudence
And then browse to http://localhost:8080/diligence-example/. Note that the example expects an unprotected MongoDB instance running at localhost.
Rails Skeleton
Ruby on Rails, or just "Rails," is a popular web development framework for the Ruby programming language. It combines a traditional MVC approach with a RESTful orientation backed by relational database stores (MySQL, Postgres). Rails enjoys the elegant, often-imitated, ActiveRecord ORM, and a powerful "scaffolding" feature that automatically generates models, views and controllers to which you can add your code.
Rails is known to work very well on the JVM, but it can sometimes be painful to install everything and get it running. The Sincerity skeleton can do it all for you with one command:
sincerity add rails : install
This may take a few minutes: Rails is quite massive.
To start you server:
sincerity start rails
The default port is 3000, so point your browser to http://localhost:3000.
If you're looking for a more strictly RESTful, minimalist alternative to Rails, while sticking to Ruby, take a look at Prudence. (Disclosure: Prudence has also been created by Three Crickets.)
Fleshing Out
The skeleton will create an application for you under "/app/", so you don't have to run "rails new" to create one. Indeed, the correct way to start a new Rails project in Sincerity is simply to create a new container for it. That's the whole point of Sincerity!
The skeleton comes with a plugin to handle the "rails" tool for you, similarly to how Sincerity's Ruby plugin adds commands for common Ruby tools, such as "gem" and "rake". The benefit of this approach is that you do not have to explicitly change to the "/app/" directory to run the tool, and indeed you can chain it as is usual with Sincerity commands. It should work identically to the usual "rails" command: simple prefix "sincerity" to it. Examples:
sincerity rails generate controller home index sincerity rails generate scaffold Post name:string title:string content:text sincerity rake db:migrate
Or as one Sincerity command:
sincerity use mycontainer : rails generate controller home index : rails generate scaffold Post name:string title:string content:text : rake db:migrate
A quick note: Ruby is a bit sluggish to start up on the JVM, which you will notice when running "rails". However, don't let this worry you: once it's up and running, your Rails application will perform marvelously.
And that's it: from here on, it's all standard Rails goodness. You can go ahead with the tutorial, skipping step 3.2 ("Creating the Blog Application").
MySQL, PostgreSQL and SQLite are all supported out of the box, identically to how Rails works on other platforms.
If you need to access the Rails source code, you'll find it under "/libraries/ruby/lib/ruby/gems/1.8/gems/", which is where all Ruby gems will be installed in your container.
Extras
Though the "rails" tool does support a daemon mode, Sincerity's logging plugin is far more powerful and is strongly recommended. To install:
sincerity add service : install
The following command will install the Rails skeleton with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add rails : add service : install : service rails start
To stop it:
sincerity use mycontainer : service rails stop
Note that Sincerity's logging plugin won't do you much good out of the box, because Rails uses Ruby's logging system, not the JVM's. However, it should be easy implement your own Ruby logger that delegates to standard JVM logging if that seems exciting to you.
Django Skeleton
Django is a popular web development framework for the Python programming language. It relies on a traditional MVC approach backed by relational database stores (MySQL, Postgres). Django enjoys a large ecosystem of drop-in features and snippets, but already provides many features right out of the box. Much the appeal of Django is the Python programming language: elegant, clean and supported by what must be the friendliest and most welcoming community of any programming language.
There are many advantages for running Django on the JVM instead of on the CPython reference platform: great performance, much improved scalability (there is no GIL in Jython), as well as access to any JVM library in addition to Python libraries. Of course, Sincerity makes it extremely easy and transparent to add both kinds of libraries as dependencies.
If you're looking for RESTful, minimalist alternative to Django, while sticking to Python, take a look at Prudence. (Disclosure: Prudence has also been created by Three Crickets.)
Django can be difficult to install and get running on Jython, but of course it's trivial with Sincerity:
sincerity add django : install
This may take a few minutes: Django is quite massive!
To start you server:
sincerity start django
The default port is 8000, so point your browser to http://localhost:8000.
Fleshing Out
The skeleton already has a minimal project ready for you under "/project/", so you don't have to run "django-admin.py startproject" to create one. Indeed, the correct way to start a new Django project in Sincerity is simply to create a new container for it. That's the whole point of Sincerity!
However, if you need to access "django-admin.py", it is located under your "/executables/" directory, so:
sincerity execute django-admin.py
Much of the work with Django involves running "manage.py", which in this skeleton is located under "/project/manage.py". You can run it easily, from anywhere in the container, with a handy plugin:
sincerity manage
Note that Python is a bit sluggish to start up on the JVM, which you will notice when running "manage". However, don't let this worry you: once it's up and running, your Django application will perform very well.
And that's it: from here on, it's all standard Django goodness. You can go ahead with the tutorial, skipping the short "Creating a project" step.
Well, just one quick note: the database backend uses JDBC drivers (the JVM's relational database interface) instead of Python drivers, so the database engine names in your "settings.py" are a little bit different than in the official tutorial. You'll see the supported options commented in "settings.py". JDBC drivers for MySQL and PostgreSQL are included in the skeleton, but you must install the Oracle JDBC driver on your own. Also note that SQLite is not supported at this time.
If you need to access the Django source code, you'll find it under "/libraries/python/Lib/site-packages/", which is where all Python libraries will be installed in your container.
Extras
Adding the service plugin is strongly recommended. To install:
sincerity add service : install
The following command will install the Django skeleton with the recommended plugins into a Sincerity container created in the current directory, and then start it a service:
sincerity create mycontainer : add django : add service : install : service django start
To stop it:
sincerity use mycontainer : service django stop
Note that Sincerity's logging plugin won't do you much good out of the box, because Django uses Python's logging system, not the JVM's. However, it should be easy implement your own Python logger that delegates to standard JVM logging if that seems exciting to you.
OutOfMemoryError? Installing and starting Django in the same Sincerity command may exhaust your JVM's PermGen space. Try installing and starting via separate commands. For more tips, see the FAQ.
LWJGL Skeleton
The JVM is growing in popularity as a platform for game designers, due to its ability to easily have the game run on many operating systems, as well as in browsers. Much of this growth is due to the excellent LWJGL library, which makes easy to use hardware-accelerated features, such as 3D graphics and 3D sound, and to accept input from gaming controllers. LWJGL relies on native extensions to the JVM, and supports Linux, Windows, Mac OS X and Solaris. (This author's favorite game, Minecraft, is based on it!)
To install the barebones skeleton:
sincerity add lwjgl : install
To start your game:
sincerity start lwjgl
This "lwjgl" program will detect your operating system, install the relevant native binaries into the container (if they aren't already installed), and then start the "game" program… except that with this barebones skeleton, there is no game to start.
Fleshing Out
Create a "/programs/game.js" that starts up your game. If you want your game to be written only in Java, this likely means delegating to your main class, like this:
sincerity.run('delegate:main', ['org.mycoolgame.Main'])
However, don't rule out writing your game in JavaScript, or the host of other languages easily installable in Sincerity! You can even "drop down" to Java when you some low-level work, and keep the main game logic in a higher-level language.
This is especially useful if you want to provide a way for the community to provide plugins for your game: it would make it easier for novice programmers to contribute, and also allow such plugins to be distributed as simple text files. If you go this route, consider using Scripturian to allow high-performance, muli-threaded integration of the language engines.
Extras
For something to play with, see the "lwjgl.example" add-on. It includes a simple Space Invaders clone:
sincerity add lwjgl.example : install : start lwjgl
The Sincerity Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.
