How to Set Java Environment Variables System-Wide on Ubuntu

Once OpenJDK is installed, plenty of Java-based software — DSpace included — still needs to know exactly where Java lives, and how much memory to give it. That's what JAVA_HOME and JAVA_OPTS are for. Setting them in /etc/environment makes them available to every user and every service on the machine, instead of just your own login shell.

Why /etc/environment (and Not ~/.bashrc)

It's common to see JAVA_HOME exported inside a personal ~/.bashrc or ~/.profile. That works for interactive logins as that one user — but background services like Tomcat, or another system user like dspace, won't see it. /etc/environment is read system-wide by PAM at login, independent of which shell or user is involved, which is exactly what a server process needs.

Step 1: Confirm Your Java Installation Path

Before setting JAVA_HOME, confirm exactly where Java was installed — the path differs slightly depending on the JDK version and architecture.

update-alternatives --list java

Purpose: Find the exact Java installation path
Explanation: Lists all Java versions registered on the system along with their full install paths — useful when multiple JDKs are present, or to confirm the exact path before setting JAVA_HOME.

# Should show OpenJDK 17 (or whichever version you installed)

java -version

Purpose: Verify the active Java version
Explanation: Confirms which Java version the system currently defaults to before you wire up environment variables around it.

Step 2: Edit /etc/environment

sudo nano /etc/environment

Purpose: Edit the system-wide environment file
Explanation: Opens the file where Ubuntu stores environment variables that apply to every user session on the machine, not just your own.

Add the following two lines to the file (adjust the JDK version/path to match what Step 1 showed):

JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"

Purpose: Set JAVA_HOME
Explanation: Points JAVA_HOME at the Java installation directory. Many Java applications — including build tools and application servers — look for this variable directly rather than relying on the java command being on PATH.

JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"

Purpose: Set default Java runtime options
Explanation: Configures the maximum heap size (512MB), initial heap size (64MB), and forces UTF-8 file encoding — important for handling non-English text correctly in library and repository metadata.

Common mistake: Unlike a shell script, /etc/environment does not support the export keyword or variable expansion (no $OTHER_VAR references). Each line must be a plain NAME="value" pair, or the file will fail to parse correctly on next login.

Step 3: Apply and Verify the Changes

Save and close the editor (Ctrl+O, Enter, Ctrl+X in nano), then apply the changes to your current shell:

source /etc/environment

Purpose: Reload environment variables
Explanation: Applies the changes made to /etc/environment to your current shell session, without needing to log out and back in.

echo $JAVA_HOME

Purpose: Verify JAVA_HOME
Explanation: Displays the current value of JAVA_HOME to confirm it was set correctly.

echo $JAVA_OPTS

Purpose: Verify JAVA_OPTS
Explanation: Displays the current value of JAVA_OPTS to confirm the memory and encoding settings were applied.

Note: source /etc/environment only updates your current terminal session. New SSH logins, cron jobs, and system services (like Tomcat) will pick up the new values automatically on their next start — but any already-running process, including a shell you had open before editing the file, needs to be restarted or re-sourced to see the change.

What These Variables Are Used For

Variable	Used By	Purpose
JAVA_HOME	Maven, Ant, Tomcat, most Java build tools	Tells the tool exactly which JDK installation to use, rather than guessing from PATH.
JAVA_OPTS	Tomcat, standalone Java apps, some build scripts	Passes JVM runtime flags — heap size, encoding, GC settings — at startup.

Heads up for Tomcat specifically: Tomcat 10 on Ubuntu reads its own separate environment file — /etc/default/tomcat10 — rather than /etc/environment. If you're setting memory options for Tomcat itself (e.g. a 2GB heap for a DSpace backend), that needs to be configured there as well; setting JAVA_OPTS in /etc/environment alone won't reach Tomcat's process.

Where People Usually Go Wrong

• Using export VAR=value syntax in /etc/environment — this file uses plain NAME="value" pairs only, with no export keyword.
• Referencing another variable inline, like PATH="$JAVA_HOME/bin:$PATH" — /etc/environment doesn't expand variables, so this gets treated as a literal string instead of being resolved.
• Expecting an already-open terminal or already-running service to pick up the change automatically — it won't, until it's restarted or the file is re-sourced.
• Setting JAVA_OPTS here and expecting it to control Tomcat's memory — Tomcat reads its own /etc/default/tomcat10 file instead.

Building this for DSpace specifically? This is one of the early setup steps in the full backend install. See the DSpace Backend Installation Guide for how it fits alongside Maven, Ant, PostgreSQL, and Solr.