Getting Started

Remove any Java installation you may have on your PC.

You should look on the Oracle site for the "Java SE" installer, which is the "Standard Edition" of Java. You will probably be required to create an Oracle account and login before being able to download. The OpenJDK version of Java should also work fine if you prefer open source software.

The installation package will probably install both the JDK and the JRE. The JRE - 64 bit - can be any version and generally it will auto-upgrade to the latest. To make your installation future-proof, install the java JDK in some folder like C:\Local\Javas\jdk1.8.0_152 and make a symbolic link to it with a generic name, like

Now you can refer to C:\Local\jdk8 in your scripts and when you update the java (minor) version you just change the link, not the scripts. The Java JRE can be installed to the default folder (C:\Program Files).

Install git for your OS.

Install MySQL Community Server v8: any later versions have not been tested yet.

For a future-proof installation you should not install MySQL as a Service, but run it manually when needed because one day you might have more than one version to use.

If you already have a MySQL installation, you may use it. Just check that the "lower_case_table_names" system variable is set to "2": if it’s not, it can’t be changed after installation so you can either reinstall, install a new instance or live with it (see below).

If you don’t have a MySQL installation already, the easiest way to install it is by downloading the "MySQL installer":

After installation, make a symbolic link to the server folder with a generic name, like

Now you can refer to C:\Local\mysql80 in your scripts and when you want to use a different installation you just change the link, not the scripts. In order to start/stop the MySQL server you should create two scripts and put their shortcut somewhere easy like the desktop or the taskbar.

It is very convenient to set an empty password for root on the development computer (the above script won’t work otherwise):

When you start MySQL you may get a few errors and warnings like "Failed to set up SSL" or "Cannot open Windows EventLog": you can safely ignore them as long as the process doesn’t stop.

You can edit the source files and compile the binaries in any IDE. This documentation only shows how to set up Eclipse though. You don’t actually need an IDE to develop a web application, but it can make life a lot easier compared to editing files in a generic text editor and compiling from the command line.

Install the latest version of Eclipse IDE for Enterprise Java and Web Developers. Be sure to install the 64 bit "Enterprise Java and Web" version.

With a single installation of Eclipse you can have as many workspaces as you like. For big projects involving multiple branches and many people, you might want to create at least two workspaces, one for your own development and another one for checking other people’s work or for deployment. It is very convenient to create a different shortcut for each workspace. Using the "-data" command line option you can specify which workspace you want to use. For example:

Run Eclipse with the chosen workspace and click on the "Workbench" or "Hide" icon to the right of the "Welcome to Eclipse" page.

Update your installation with "Help > Check for Updates" and follow the instructions. Failing to do so might prevent you from adding a Tomcat server later.

From the "Window > Preferences > Gradle" dialog set the "Java home" entry to your JDK installation, which would be C:\Local\jdk8 if you followed the instructions above. This is very important. Failing to do so may result in a "java facet" mismatch error on compilation.

Set the editors file encoding to UTF-8, at least "General > Workspace > Text file encoding" and "Web > CSS Files > Encoding":

The "New text file line delimiter" shown in the above image is also better set to "Unix".

Also set UTF-8 in the "Content Types > Text > Java Properties File > Default encoding" field and be sure to click on "Update" before applying the changes:

Add the previously donwloaded JRE as a new Runtime in "Window > Preferences > Java > Installed JREs" and set it as the default. Also set the "Window > Preferences > Java > Compiler > JDK Compliance" accordingly (that would be "1.8" for Java 8).

In order to better spot errors and stack traces, you should considerably increase the console output buffer or remove the limit altogether using the "Window > Preferences > Run/Debug > Console" options:

Node.js is not strictly needed but it can be useful. Install the latest LTS version.

The Yada Framework sources are hosted on the public GitHub site. To access the GitHub repository use your GitHub credentials on the yadaframework repo. The git url should be git@github.com:xtianus/yadaframework.git.

Once you have the repository credentials, connect Eclipse:

On the "Branch Selection" dialog you should NOT select "master" but the latest versioned branch, for example "0.7.3".

On the "Local Destination" dialog you need to select a local folder where to clone the repository. Here we assume that you are going to create a new Eclipse project called MySiteProject (will be explained later) and add it to a git repository called mysite. It is very important that you store both the Yada Framework repository and your application repository in a common parent folder that is specific to the current project, for example C:\work\git-mysite, otherwise relative paths in the build file won’t work and you’ll have to customise them.

You should create your base git folder before proceeding. The Yada Framework will have to be cloned inside this folder, with a name of "yadaframework":

At the end, when you later also add the "mysite" git and web project, the filesystem structure will be like the following, where "mysite" is any new project that uses the Yada Framework:

When you have connected the yada repository, you can switch to the "Java Perspective" in Eclipse.

Create a new Eclipse Project using "File > New > Project…​ > Gradle > Gradle Project" menu. Use any name you like ("MySiteProject" in the above example) and accept all defaults. Two new Java projects will be created in your workspace.

The following fixProject.sh bash script can be used in order to get rid of the lib subproject:

You can find a version of it in YadaTools/scripts/fixProject.sh. It should be run in the parent folder of the project passing the project folder itself as an argument:

After the project has been fixed, select the old projects in Eclipse and do a "refresh" accepting to delete the lib project when prompted.

Optional: edit the /MySiteProject/gradle/wrapper/gradle-wrapper.properties file changing the distributionUrl to match the version of Gradle that you want to use. For example distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip. This is only needed if the gradle you want to use is not yet available in Eclipse. Right-click the project and choose "Gradle > Refresh Gradle Project" to update the version of Gradle used.

You can choose to add an external Tomcat server or use the embedded version. In the first case, you should be using the "Enterprise" version of Eclipse. If not, you should at least install the "Eclipse Web Tools Platform" (WTP) plugin.

After connecting to the GitHub repository as explained above, you can import the needed projects using the "File > Import…​ > Gradle > Existing Gradle Project" menu.

To import most Yada Framework projects at once you could just import the "YadaWebCommerce" project and rely on dependency resolution to automatically import everything else. Don’t worry about Gradle versions here: the version used will be the one configured inside the imported projects.

The YadaTools project should also be imported because you will later need to copy some files from it.

If the imported projects have any errors, first of all right-click and choose "Gradle > Refresh Gradle Project". If it complains about some unbound system library, open "Properties > Java build path > Libraries" and remove the library.

You should now have, in your workspace, the following Yada projects:

The next step is to create a git repository to store your projects. You must definitely use git to store your files, because after sharing the project to the repo it will be moved to the same root folder of the Yada projects so that relative paths in the build file will work effortlessly.

For a quick test, you can just create a local repository. It must reside in the same root folder that was used when cloning Yada, that was C:\work\git-mysite in the previous example. The name can be anything you like. Here we use 'mysite':

You can also use any public provider like GitHub or a private server installation based for example on GitLab and clone the repository locally, being careful to create the correct directory tree.

When using GitLab, let it create a default readme.md file so that you’ll be able to check out the repository easily (there should be a similar option on GitHub). Then add the repository location to the Git Perspective as done for the Yada Framework.

After the repository has been added to Eclipse, to add your project to the git repository right-click on it and choose "Team > Share Project…​". In the dialog you should just select the correct repository and accept the defaults. The resulting filesystem structure will be as follows:

Finally edit .gitignore in the root of your project to make it look like the following:

If you don’t see the file, you should change the workspace filter. Next to the "Package Explorer" title there’s a menu icon containing the "Filters…​" item. Ensure that ".* resources" is NOT selected.

Replace your build.gradle with the contents of /YadaTools/scripts/template.gradle.

The lines marked with // CHANGE THIS !!! should be edited to suit your needs.

The default environments are "dev" for "Development", "tst" for "Test" and "prod" for "Production". You can rename them (or also add/remove some) using the "envs" property in the yadaInit task of the build, but the envs array must always have the "development" environtment first and the "production" environment last in order to create a correct configuration.xml file. For a list of all other options for the yadaInit task see /YadaTools/src/main/groovy/net/yadaframework/tools/YadaProject.groovy

Replace your settings.gradle with the following:

You should change the project name to whatever you used. The above assumes that you cloned the yadaframework repository in the same root folder of your project repository as explained in "Add the repositories" above. This setup is needed to use YadaWeb class files directly instead of going through the jar, and is handy when you plan to work on the YadaWeb sources to fix and improve them.

More information on the wtp syntax here and here.

Copy the /YadaTools/scripts/sass.properties file into the project folder.

Ensure you have these folders in your project before the next step, and create them when missing:

Use the Gradle > Refresh Gradle Project project menu item to initialise the project. Check the Elcipse console (Window > Show view > Console) to see if there are any problems.

Open a command prompt in the root folder of your project (e.g. C:\work\git-mysite\MySiteProject) and run gradlew yadaInit --no-daemon.

This task will add the java core Spring configuration and some default files that later will have to be either deleted or customised. The "--no-daemon" option is to stay on the safe side.

Refresh your project in Eclipse (F5). If you see compilation errors ensure that you’re just missing some classpath libraries and do a "Refresh Gradle Project" again. If you still have errors, try to fix them ;-) For example you might need to remove the dependency on YadaWebSeurity classes if you didn’t want to use it.

This may be a good time to commit and push to git.

In case of compilation errors, the first thing to do is to run a "Refresh Gradle Project" on the affected project or the including project. If errors persist, check that you have imported all the needed Yada projects. Also be sure to have "Projects > Build Automatically" checked and try with a "Project > Clean…​".

If you get an error like

CHKJ3000E: WAR Validation Failed: org.eclipse.jst.j2ee.commonarchivecore.internal.exception.DeploymentDescriptorLoadException: WEB-INF/web.xml

you may fix it just by forcing a validation on the project via the menu.

If Tomcat doesn’t start, it might have stale data. Try with a "Clean…​" on the server. If everything fails, stop the server and delete the content of the Deploy folder, for example C:\local\Deploy\myProject. Then do a "Publish" on the server. If you can’t delete some file because Windows says it’s open, you’ll need to quit Eclipse and be sure that there are no ghost Tomcat processes running. In extreme cases, you might need to restart your PC.