A simple shell script has been added to this project to build the application and bundle it with all its dependencies in a single jar file. Just execute
$ ./build.sh
and a jar-file will appear in the root-dir of this project.
$ ./build.sh
This command is everything it takes to build a functioning version of azas. There are however some dependencies:
- Java 8 (Java 7 may or may not work. Don't find out during production)
- wget
Just for reference you also need
- tar
- gzip
- bash
But these are already installed on most linux systems.
This repository contains an example configuration that provides a basic setup already. Adjust this file to your needs. It should be documented well enough.
You need to assemble a list of all councils in the form of a json file like this one:
[
{
"uni": "Uni Konstanz",
"address": "no clue",
"email": "idk",
"token": "efgh"
}, {
"uni": "FSU Jena",
"address": "Max-Wien-Platz 1",
"email": "fsr@paf.uni-jena.de",
"token": "abcd"
}
]
This list can be added to the DB with the following command
$ java -Dconfig.file=/path/to/application.conf -Ddatabase.seed=/path/to/json/file -jar azas-<version>.jar
This only works once. Later additions can only be done by manipulating the database directly (via phpmyadmin for instance).
$ java -Dconfig.file=/path/to/application.conf -jar azas-<version>.jar
This starts the application. You can either use screen or write systemd files to daemonize the application. It's up to you.
AZaS has no built in TLS support. You should therefore use an encrypting reverse proxy. Both apache2 and nginx are capable of that.
AZaS provides a default frontend that you can use. There are two ways to use it:
Just navigate to the URL where the azas backend is running. For example
http://localhost:8080/
when you use no config.
Using System.js you can embed AZaS in your own website. An example might look like this:
<!DOCTYPE html>
<html>
<head>
<title>AZAS</title>
<meta charset="utf-8" />
</head>
<body>
<!-- Load polyfills -->
<script src="http://url.to.azas/assets/modules/angular2/bundles/angular2-polyfills.min.js"></script>
<script src="assets/modules/systemjs/dist/system-polyfills.js"></script>
<!-- Configure module loader -->
<script src="http://url.to.azas/assets/modules/systemjs/dist/system.js"></script>
<script>
System.config({
baseURL: 'https://url.to.azas/assets/modules',
defaultJSExtensions: true,
packages: {
azas: {
format: 'register'
}
}
});
</script>
<!--
Load dependencies. This is not strictly necessary but you will want to
do it if you do not like loading times longer than 10 seconds
-->
<script src="http://url.to.azas/assets/modules/rxjs/bundles/Rx.min.js"></script>
<script src="http://url.to.azas/assets/modules/angular2/bundles/angular2.dev.js"></script>
<script src="http://url.to.azas/assets/modules/angular2/bundles/http.min.js"></script>
<!-- Load app -->
<script>
System.import('azas/main').then(function(module) {
// Initialize the application with the URL to the
// API endpoint.
module.azasBootstrap('http://url.to.azas');
}, console.error.bind(console));
</script>
<!--
The application will be initialized within these tags. What is in there
initially will only be displayed until the app is fully loaded. The
perfect place for a beautiful spinning gif.
-->
<azas>Loading...</azas>
</body>
</html>
You can also check src/main/resources/html/index.html
for reference.
The build system is optimized for fast development iterations. The
fabulous sbt-revolver
plugin is integrated so you do not have to
interact withthe build system at all during development. Fire up azas by
typing sbt ~re-start
. Every time you change a file the application is
automatically recompiled and restarted.
The sbt-file of this project is a tic more complicated than your usual
run-off-the-mill scala project to ensure easier deployment. It seems
that authors of sbt-web plugins think that it is OK to just start your
projects using sbt run
and that all files can be served directly from
the target
directory.
I think that it is very bad practice to do that because it invites
people to fiddle with systems that are in production status. The only
way you should ever deploy this application is by using the jar-file
that build.sh
produces and you should only actually use released
versions. I try very hard to make them as stable as possible and every
official release is tested extensively before an actual version number
is assigned.
AZaS uses resource generators to provide the frontend that is written in
typescript using the framework angular2
. When you change anything in
the sbt-file make sure that the following run configurations still
provide a working frontend:
./build.sh && java -jar azas*.jar
sbt run
sbt ~re-start
This is not covered by unit tests. They only test the backend. Frontend unit testing is a great way to make yourself less productive. Even if you do it it would be careless to release without having actually used it once or twice.
For a given minor release the database is guaranteed to stay compatible. For a new minor release it is likely to have a totally new scheme. Given the short lifetime of deployments this is no contradiction to semantic versioning. I will provide no database upgrade paths at all until i see an actual need for them.
The API will stay compatible over a given major release. All API endpoints will be prefixed by a version (e.g. "/v1/addpart"). However i reserve the possibility to make a specific endpoints answer with status code 501 (Not implemented) for all requests if structural changes require it. This makes it obvious to developers of alternative frontends what the problem is. Changed behaviour of a given endpoint over the lifecycle of a major release is considered a critical bug (excluding 501 of course).