Help:Toolforge/Web/Java

Toolforge
Toolforge technical documentation Toolforge administrator documentation Help and communication List of tools Terms and conditions Rules Glossary Technical documentation resources
Getting started Cloud VPS and Toolforge at a glance About Toolforge Toolforge quickstart guide How-tos, tutorials and walkthroughs Create a Wikimedia developer account Access Toolforge instances with PuTTY and WinSCP Troubleshooting Toolforge
Developing tools Tool accounts Developing successful tools Develop tools in Java Develop tools in Mono/.NET Develop tools in Python Develop tools using Pywikibot framework Web servers for tools Grid engine Kubernetes
Additional documentation Version control in Toolforge Elasticsearch for Toolforge Redis for Toolforge Dumps and Toolforge Database

Overview

Java is one of the programming language runtimes supported by Toolforge's webservice command.

Play and similar JVM-based frameworks

• webservice --backend=kubernetes jdk11 start|stop|restart|shell BINARY

Play Framework projects (and other JVM-based projects that have one executable to start the application) can be run on Toolforge.

1. In order to work on Toolforge, the following Play configuration changes need to be made:

   # Secret key
   # ~~~~~
   # The secret key is used to secure cryptographics functions.
   # If you deploy your application to several instances be sure to use the same key!
   # On Toolforge, we will make a startup script that specifies play.crypto.secret
   # using a command line option reading from a private file.
   play.crypto.secret="changeme"
   
   # Port
   # ~~~~~
   # On WMF Toolforge, the port used by kubernetes webservice is 8000/TCP
   http.port=8000
   
   # HTTP context
   # ~~~~~
   # Your tool will be available at https://$TOOLNAME.toolforge.org/.
   # Play usually expects to be operating at the root of a domain, so this setting is
   # required for routes to work properly.
   play.http.context="/"
   

2. The application secret can be stored in a private file with 440 permissions.
3. Build the project.
4. After building the project, start your webservice:

   webservice --backend=kubernetes jdk11 start '$EXECUTABLE -Dplay.crypto.secret="$(cat /data/project/$TOOLNAME/app_secret)"'.

For more details, see User:Sn1per/Play on Tool Labs.

Tomcat

• webservice --backend=gridengine tomcat start|stop|restart

To run a JVM-based Web Application Archive (WAR) on Tomcat:

1. Setup Tomcat by running setup-tomcat. This will create a local Tomcat installation at $HOME/public_tomcat/.
2. To deploy the WAR, move it to $HOME/public_tomcat/webapps/$TOOL.war where $TOOL is the name of your tool. Archive extraction, deployment, and configuration is done automatically by Tomcat.
3. If necessary, restart Tomcat.
4. The application will be available at $TOOL.toolforge.org.
5. To test the Tomcat webservice, you can use the Tomcat sample application (available on tomcat.apache.org).

When reading Tomcat tutorials, it is helpful to know that $CATALINA_HOME under our configuration is the $HOME/public_tomcat directory created by setup-tomcat. The default Tomcat classloader will read jar files such as a MySQL JDBC driver jar that are placed in $HOME/public_tomcat/lib (i.e. $CATALINA_HOME/lib).

Troubleshooting

If your Java application is more complex, the standard memory settings might not work. Common symptoms of insufficient memory include receiving the message: There is insufficient memory for the Java Runtime Environment to continue and Tomcat stopping. See Help:Toolforge/Web § Runtime memory limits for instructions on getting the runtime memory limit increased.

To resolve an insufficient memory problem:

1. Modify your tool's JVM settings in $HOME/public_tomcat/bin/setenv.sh.
2. If the memory setting from JAVA_OPTS is too low, you'll get the well-known OutOfMemoryError from Java.
3. In some cases, Tomcat may not stop following an OOM error. Killing the grid engine job using qdel may be your only solution.

Communication and support

We communicate and provide support through several primary channels. Please reach out with questions and to join the conversation.

Communicate with us

	Connect	Best for
Phabricator Workboard	#Cloud-Services	Task tracking and bug reporting
IRC Channel	#wikimedia-cloud connect Telegram bridge mattermost bridge	General discussion and support
Mailing List	cloud@	Information about ongoing initiatives, general discussion and support
Announcement emails	cloud-announce@	Information about critical changes (all messages mirrored to cloud@)
News wiki page	News	Information about major near-term plans
Cloud Services Blog	Clouds & Unicorns	Learning more details about some of our work
Wikimedia Technical Blog	techblog.wikimedia.org	News and stories from the Wikimedia technical movement

See also

• Help:Toolforge/Web