Cloud
Data Center 7.19
Versions

Installing Confluence on Linux from Archive File

Installing Confluence on Linux

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

In this guide we'll run you through installing Confluence in a production environment, with an external database, manually using a zip file.

This method gives you the most control over the installation process.


Other ways to install Confluence: 

  • Evaluation - get your free trial up and running in no time.
  • Installer – install Confluence using the Linux installer. 
  • Windows – install Confluence on a Windows server. 

On this page:

Before you begin

Before you install Confluence, there are a few questions you need to answer. 


Are you using a supported operating system and Java version?
Tell me more...

Check the Supported Platforms page for the version of Confluence you are installing. This will give you info on supported operating systems, databases and browsers.

Good to know:

  • We don't support installing Confluence on OS X or mac OS for production environments.
  • You'll need to install either Adoptium OpenJDK (formerly AdoptOpenJDK) or Oracle JDK. We don't support other OpenJDK binaries.
  • You can use either the JDK (Java Development Kit) or JRE (Java Runtime Environment).
  • We only support the version of Apache Tomcat that is bundled with Confluence.

Do you want to run Confluence as a service?
Tell me more...

Running Confluence as a service means that Confluence will automatically start up when your Linux server is started.

You should use the Linux installer if you want to run Confluence as a service.

If you choose not to run Confluence as a service:

  • You will start Confluence by running the start-confluence.sh file in your Confluence installation directory.
  • We recommend creating a dedicated user to run Confluence. This user must have full read, write and execute access to the installation directory and home directory.
  • Confluence will need to be restarted manually if your server is restarted.
Are ports 8090 and 8091 available?
Tell me more...

Confluence runs on port 8090 by default. If this port is already in use, the installer will prompt you to choose a different port.

Synchrony, which is required for collaborative editing, runs on port 8091 by default. If this port is already in use, you will need to change the port that Synchrony runs on after your Confluence installation is complete. See Administering Collaborative Editing to find out how to change the port Synchrony runs on. You won't be able to edit pages until Synchrony has an available port.

See Ports used by Atlassian Applications for a summary of all the ports used.

What database do you plan to use? 
Tell me more...

To run Confluence you'll need an external database. Check the Supported Platforms page for the version you're installing for the list of databases we currently support. If you don't already have a database, PostgreSQL is free and easy to set up.

Good to know:

Do you have a Confluence license?

Tell me more...

You'll need a valid license to use Confluence.

Good to know:

  • If you have not yet purchased a Confluence license you'll be able to create an evaluation license during setup.
  • If you already have a license key you'll be prompted to log in to my.atlassian.com to retrieve it, or you can enter the key manually during setup.
  • If you're migrating from Confluence Cloud, you'll need a new license.
  • Unable to render {include} The included page could not be found.

Is your JAVA_HOME variable set correctly?
Tell me more...

Before you install Confluence, check that you're running a supported Java version and that the JAVA_HOME environment variable is set correctly.

Confluence can only run with Oracle JDK or JRE.

To check your Java version:

$ java -version

To check your JAVA_HOME variable is set correctly:

$ echo $JAVA_HOME

If you see a path to your Java installation directory, the JAVA_Home environment variable has been set correctly. If a path is not returned you'll need to set your JAVA_HOME environment variable manually before installing Confluence.

Have you created a dedicated user to run Confluence?
Tell me more...

We strongly recommend running Confluence as a dedicated user.

You should create this user before you begin, so that when creating the installation and home directories, you can give this user appropriate read and write permissions.

In this example, we'll create a user called confluence:

$ sudo /usr/sbin/useradd --create-home --comment "Account for running Confluence" --shell /bin/bash confluence

See Creating a Dedicated User Account on the Operating System to Run Confluence for more information.

There’s a known issue during setup where a load balancer (or proxy) pings the server and breaks Confluence installation or migration to Data Center. See CONFSERVER-61189 - Getting issue details... STATUS
During installation, you need to disable load balancer health checks and make sure you don’t open multiple tabs that point to the same Confluence URL.

Install Confluence

1. Download Confluence

Download the tar.gz file for your operating system - https://www.atlassian.com/software/confluence/download. 

2. Create the installation directory

  1. Create your installation directory – this is where Confluence will be installed. Avoid using spaces or special characters in the path. We'll refer to this directory as your <installation-directory>. 
     

    Show me how to do this...

    In this example we'll call our installation directory confluence:

    $ mkdir confluence

  2. Extract the Confluence tar.gz file to your <installation-directory>. We recommend using a GNU version of the archive utility, especially on Solaris.
     

    Show me how to do this...

    Change to the directory where you downloaded Confluence then execute these commands:

    $ tar -xzf atlassian-confluence-X.X.X.tar.gz -C <installation-directory>
$ cd <installation-directory>
$ tar -xf atlassian-confluence-X.X.X.tar

    Replace x.x.x with your Confluence version and <installation-directory> with the full path to the directory you created in the last step.

  3. Give your dedicated Confluence user read, write and execute permission to your <installation-directory>. 
     

    Show me how to do this...

    In this example we're changing ownership of the installation directory and giving the user confluence read, write and execute permissions.

    $ chown -R confluence <installation-directory>
$ chmod -R u=rwx,go-rwx <installation-directory>

3. Create the home directory

  1. Create your home directory – this is where Confluence application data like logs, search indexes and files will be stored. This should be separate to your installation directory, with no spaces or special characters in the path. We'll refer to this directory as your <home-directory>. 
     

    Show me how to do this...

    In this example we'll call our home directory confluence-home:

    $ mkdir confluence-home

  2. Give your dedicated Confluence user read, write and execute permissions to the <home-directory>.
     

    Show me how to do this...

    In this example we're changing ownership of the home directory and giving the user confluence read, write and execute permissions.

    $ chown -R confluence <home-directory>
$ chmod -R u=rwx,go-rwx <home-directory>
  3. Edit <installation-directory>\confluence\WEB-INF\classes\confluence-init.properties.

  4. At the bottom of the file, enter the absolute path to your <home-directory>. This tells Confluence where to find your <home-directory> when it starts up.
     

    Show me how to do this...

    You can edit the confluence.init.properties file any text editor.

    1. Scroll to the bottom of the text and find this line:

      # confluence.home=c:/confluence/data

    2. Remove the # and the space at the beginning of this line (so Confluence doesn't read the line as a comment) and add the absolute path to your home directory (not a symlink). For example:

      confluence.home=/var/confluence-home

4. Check the ports

By default Confluence listens on port 8090. If you have another application running on your server that uses the same ports, you'll need to tell Confluence to use a different port. 
 

Show me how to do this...

To change the ports:

  1. Edit <installation-directory>\conf\server.xml

  2. Change the Server port (8000) and the Connector port (8090) to free ports on your server.

    In the example below we've changed the Server port to 5000 and the Connector port to 5050.

    Server port="5000" shutdown="SHUTDOWN" debug="0">
  <Service name="Tomcat-Standalone">
    <Connector port="5050" connectionTimeout="20000" redirectPort="8443"
        maxThreads="48" minSpareThreads="10"
        enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
        protocol="org.apache.coyote.http11.Http11NioProtocol" />

Linux won't allow you to bind to ports less than 1024. If you want to run Confluence on port 80, for example, you could use a reverse proxy to redirect traffic from port 80. See Using Apache with mod_proxy.


5. Enhance directory security 

Increase the security of your <installation-directory> with an extra layer of file and folder permissions.

Show me how to do this...

In the examples below, we've assumed that the tar.gz file was extracted and saved under the directory: /opt/atlassian/confluence , and that a user called confluence has been created for the Confluence runtime environment.

These commands should be executed from the parent directory of the Confluence installation folder. So, in this example, the command would be executed from /opt/atlassian :

export install_dir=/opt/atlassian/confluence
export username=confluence

chmod -R 550 "$install_dir"

# Permission 700 for "work" / "temp" and "log" folders are important to run Confluence properly
chmod -R 700 "$install_dir/work"
chmod -R 700 "$install_dir/temp"
chmod -R 700 "$install_dir/log"

chown "$username" "$install_dir"
chown -R "$username" "$install_dir/bin"
chown -R "$username" "$install_dir/conf"
chown -R "$username" "$install_dir/confluence"
chown -R "$username" "$install_dir/jre"
chown -R "$username" "$install_dir/lib"
chown -R "$username" "$install_dir/synchrony-proxy"
chown -R "$username" "$install_dir/webapps"

This is how it should look like:

xyz:/opt/atlassian/confluence$ ls -la
total 404
drwxr-xr-x 14 confluence root   4096 Jan  9 14:26 .
drwxr-xr-x  3 root       root   4096 Jan  9 14:25 ..
drwxr-xr-x  3 root       root   4096 Jan  9 14:26 .install4j
-r-xr-x---  1 root       root  20577 Jan  5 12:53 BUILDING.txt
-r-xr-x---  1 root       root   6375 Jan  5 12:53 CONTRIBUTING.md
-r-xr-x---  1 root       root  58153 Jan  5 12:53 LICENSE
-r-xr-x---  1 root       root   2401 Jan  5 12:53 NOTICE
-r-xr-x---  1 root       root   2324 Jan  5 12:53 README.html
-r-xr-x---  1 root       root   3479 Jan  5 12:53 README.md
-r-xr-x---  1 root       root   1224 Jan  5 12:53 README.txt
-r-xr-x---  1 root       root   7075 Jan  5 12:53 RELEASE-NOTES
-r-xr-x---  1 root       root  16982 Jan  5 12:53 RUNNING.txt
dr-xr-x---  3 confluence root   4096 Jan  9 14:25 bin
dr-xr-x---  3 confluence root   4096 Jan  9 14:25 conf
dr-xr-x--- 26 confluence root   4096 Jan  9 14:25 confluence
-rw-r--r--  1 root       root 122407 Jan  9 14:26 install.reg
dr-xr-x---  7 confluence root   4096 Jan  9 14:25 jre
dr-xr-x---  2 confluence root   4096 Jan  9 14:25 lib
dr-xr-x---  2 root       root  77824 Jan  9 14:25 licenses
drwx------  2 confluence root   4096 Jan  9 14:26 logs
dr-xr-x---  4 confluence root   4096 Jan  9 14:25 synchrony-proxy
drwx------  3 confluence root   4096 Jan  9 14:26 temp
-rwx------  1 root       root  13586 Jan  5 12:53 uninstall
dr-xr-x---  2 confluence root   4096 Jan  5 12:53 webapps
drwx------  3 confluence root   4096 Jan  9 14:26 work

Note: If you've chosen the binary Linux installer, the installation folder for your Confluence instance is automatically managed by the installer script.

6. Start Confluence

  1. Run <installation-directory>/bin/start-confluence.sh to start the setup process.  
      

    Show me how to do this...

    We recommend running Confluence as your dedicated user.

    $ su -u <user>
$ ./start-confluence.sh

    If you're using Ubuntu the command is a little different:

    $ sudo su <user>
$ ./start-confluence.sh
  2. Go to http://localhost:8090/ to launch Confluence in your browser (change the port if you've updated the Connector port).


Trouble starting Confluence?

Set up Confluence

7. Choose installation type

  1. Choose Production installation. 
      
  2. Choose any apps you'd also like to install.

8. Enter your license

Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key. 

9. Connect to your database

  1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of this page for details and connection options. 
     
  2. For MySQL and Oracle, follow the prompts to download and install the required driver.  

  3. Enter your database details.  Use test connection to check your database is set up correctly.

    Advanced setup options...

    If you want to specify particular parameters, you can choose to connect By connection string. You'll be prompted to enter:

    • Database URL – the JDBC URL for your database. If you're not sure, check the documentation for your database.
    • Username and Password – A valid username and password that Confluence can use to access your database.

10. Populate your new site with content

Choose whether you'd like Confluence to populate your site with content:
 
Demonstration space...

 This option will create a space that you and your users can use to get to know Confluence. You can delete this space at any time.

Import data from an existing site...

Use this option if you have a full site export of an existing Confluence site. This is useful when you’re migrating to another database or setting up a test site.  

Good to know:

  • You can only import sites from the same or earlier Confluence version.
  • The system administrator account and all other user data and content will be imported from your previous installation.

In the setup wizard:

  • Upload a backup file – use this option if your site export file is small (25mb or less).

  • Restore a backup file from the file system – use this option if your backup file is large. Drop the file into your <confluence-home>/restore directory then follow the prompts to restore the backup.

  • Build Index – we’ll need to build an index before your imported content is searchable. This can take a long time for large sites, so deselect this option if you would rather build the index later. Your content won't be searchable until the index is built.

11. Choose where to manage users

Choose to manage Confluence's users and groups inside Confluence or in a Jira application, such as Jira Software or Jira Service Management:
 
Manage users and groups in Confluence...

Choose this option if you're happy to manage users in Confluence, or don't have a Jira application installed.

Good to know:

  • If you do plan to manage users in a Jira application, but have not yet installed it, we recommend installing Jira first, and then returning to the Confluence setup.
  • You can add external user management (for example LDAP, Crowd or Jira) later if you choose.
Connect to Jira...

 Choose this option if you have a Jira application installed and want to manage users across both applications.

Good to know:

  • This is a quick way of setting up your Jira integration with the most common options. 
  • It will configure a Jira user directory for Confluence, and set up application links between Jira and Confluence for easy sharing of data.
  • You'll be able to specify exactly which groups in your Jira app should also be allowed to log in to Confluence. Your license tiers do not need to be the same for each application. 
  • You'll need either Jira 4.3 or later, Jira Core 7.0 or later, Jira Software 7.0 or later, or Jira Service Management 3.0 or later.

In the setup wizard:

  • Jira Base URL – the address of your Jira server, such as http://www.example.com:8080/jira/ or http://jira.example.com/

  • Jira Administrator Login – this is the username and password of a user account that has the Jira System Administrator global permission in your Jira application. Confluence will also use this username and password to create a local administrator account which will let you access Confluence if Jira is unavailable. Note that this single account is stored in Confluence's internal user directory, so if you change the password in Jira, it will not automatically update in Confluence.
  • Confluence Base URL – this is the URL Jira will use to access your Confluence server. The URL you give here overrides the base URL specified in Confluence, for the purposes of connecting to the Jira application.
  • User Groups – these are the Jira groups whose members should be allowed to use Confluence. Members of these groups will get the 'Can use' permission for Confluence, and will be counted in your Confluence license. The default user group name differs depending on your Jira version:
    • Jira 6.4 and earlier: jira-users. 
    • Jira Software 7.x and later: jira-software-users
    • Jira Core 7.x and later: jira-core-users
    • Jira Service Management (formerly Jira Service Desk) 3.x and later: jira-servicedesk-users
  • Admin Groups – provide one or more Jira groups whose members should have administrative access to Confluence. The default group is jira-administrators. These groups will get the system administrator and Confluence administrator global permissions in Confluence.

12. Create your administrator account

Enter details for the administrator account.  

Skip this step if you chose to manage users in a Jira application or you imported data from an existing site. 

13. Start using Confluence

That's it! Your Confluence site is accessible from a URL like this: http://<computer_name_or_IP_address>:<port>

If you plan to run Confluence behind a reverse proxy, check out Proxy and SSL considerations before you go any further. 

Here's a few things that will help you get your team up and running:

Troubleshooting

Running into problems installing Confluence?

 Head to Installation Troubleshooting in our Knowledge Base for more help.  

Last modified on Jan 16, 2024

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.