templates.docs.installation.html Maven / Gradle / Ivy
Show all versions of spincast-website Show documentation
{#==========================================
Docs : "installation"
==========================================#}
Installation
{#==========================================
Section "installation / requirements"
==========================================#}
Requirements
-
A Java 17 JDK (have a look at the
Spincast Hotswap
plugin documentation if you want to use hot reloading)
-
A build tool able to use Maven artifacts.
{#==========================================
Section "installation / versions"
==========================================#}
Spincast versions
Spincast ultimate goal is to follow the Java LTS (Long Term Support) versions.
Note that for the moment Spincast does not follow the Semantic Versioning.
The major version is only incremented when a very important change is made (for example the Java version supported by Spincast changes).
A minor version increment can contain a breaking change.
We may switch to a more semantic versioning friendly approach in the future if this is what developers using Spincast ask! But,
for now, being able to include some breaking changes helps us improve Spincast very fast.
{#==========================================
Section "installation / Quick Start"
==========================================#}
Quick Start application
{% if spincast.spincastCurrrentVersionIsSnapshot %}
Warning! The current version,
"{{spincast.spincastCurrrentVersion}}" is a snapshot version. That means that it
can change, it is not a stable version. Do not use this
as a start for a real application!
{% endif %}
The easiest way to try Spincast is to download the Quick Start application,
which also can be used as a template to start a new application. This application already has in
place most of the boilerplate code suggested to develop a solid and flexible Spincast application.
How to run :
-
Download the Spincast Quick Start [.zip]
application.
-
Decompress the zip file, go inside the "spincast-quick-start"
root directory using a command prompt and run :
mvn clean package
This will compile the application and produce an executable .jar file
containing an embedded HTTP server.
-
Start the application using :
java -jar target/spincast-quickstart-1.0.0-SNAPSHOT.jar
-
Once the application is running, open
http://localhost:44419
in your browser!
-
The next step would probably be to import the project in your favorite IDE and start debugging it to see
how it works. The entry point of a standard Spincast application is the classic
main(...)
method. You'll find this method in class
org.spincast.quickstart.App.
Note that the Quick Start application is not a simple
"Hello World!" application. It contains some advanced (but
recommended) features, such as a custom Request Context type
and a custom WebSocket Context type! To learn Spincast from scratch, you may first want to
read the three "Hello World!" tutorials
before trying to understand the code of the Quick Start application.
{#==========================================
Section "installation / Installing from scratch"
==========================================#}
Installing Spincast from scratch
{% if spincast.spincastCurrrentVersionIsSnapshot %}
Warning! The current version,
"{{spincast.spincastCurrrentVersion}}" is a snapshot version. That means that it
can change, it is not a stable version. Do not use this
as a start for a real application!
{% endif %}
If you want to start from scratch, without using the Quick Start application
as a template, you first add the org.spincast:spincast-default:{{spincast.spincastCurrrentVersion}}
artifact to your pom.xml :
<dependency>
<groupId>org.spincast</groupId>
<artifactId>spincast-default</artifactId>
<version>{{spincast.spincastCurrrentVersion}}</version>
</dependency>
This artifact installs a set of default plugins and
provides all the required components for a Spincast application to be functional.
{% if spincast.spincastCurrrentVersionIsSnapshot %}
Since this is a SNAPSHOT version, you also have to add this repository
to your pom.xml (or build.gradle) :
<repositories>
<repository>
<id>sonatype-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
{% endif %}
When this is done, you can follow the instructions of the Bootstrapping your app
section to initialize your application. This process is very simple and simply requires you to use the
Spincast.init(args) or Spincast.configure() bootstrapper in
a main(...) method.
Here's a simple Spincast application :
public class App {
public static void main(String[] args) {
Spincast.init(args);
}
@Inject
protected void init(DefaultRouter router, Server server) {
router.GET("/").handle(context -> context.response().sendHtml("<h1>Hello World!</h1>"));
server.start();
}
}
There is a tutorial page for this simple "Hello World!"
application. On that page you can download and try the application by yourself!