Latest revision as of 21:54, 29 November 2015

Both baseDir and baseURL should point to the same location on the server — the userfiles directory that contains all user files uploaded with CKFinder. The difference between them is as follows:

• baseURL gives a full URL to the userfiles directory or a path that is relative to the domain. For example:

  <baseURL>http://example.com/CKFinderJava/userfiles/</baseURL>

  <baseURL>/CKFinderJava/userfiles/</baseURL>

• baseDir gives an absolute path to the directory on the server (a physical machine). For example:

  <baseDir>/usr/tomcat/webapps/CKFinderJava/userfiles/</baseDir>

  <baseDir>C:\tomcat\webapps\CKFinderJava\userfiles\</baseDir>

You may ask: why use two paths to point to one location?

The baseURL parameter represents the path that is used by HTTP clients. It is employed for example when CKFinder returns the URL addresses of the files.

CKFinder itself is not an HTTP client, but an application that operates on server-based files that needs absolute paths to these files to operate correctly. A specific server configuration may sometimes lead to problems with setting the absolute path based on the baseURL parameter, which leads to the malfunctioning of the application. This is where the baseDir parameter that contains the direct path to the userfiles directory may help.

Misconfiguration of baseURL and baseDir

Since setting the parameters may sometimes seem counter-intuitive, especially for the beginners, here are a couple of examples of CKFinder misconfiguration, i.e. the situation where the baseURL and baseDir settings were wrong.

Example 1: Using a Relative Path for baseDir

<!-- This configuration is wrong. -->
<baseDir>/userfiles/</baseDir>
<baseURL>/CKFinderJava/userfiles/</baseURL>

In this example the baseDir parameter contains the relative (and not absolute) path to the userfiles directory. In a Windows system with this configuration the userfiles directory will be created on the same partition that hosts the server (for example, C:\userfiles). On a Linux machine the system will try to create a /userfiles/ directory which will probably fail due to missing server permissions to create new directories in /.

Example 2: Incoherent Directory Paths

<!-- This configuration is wrong. -->
<baseDir>C:\userfiles</baseDir>
<baseURL>/CKFinderJava/userfiles/</baseURL>

In this example baseDir is set to an absolute path, but the parameter points to a different location than baseURL that is set relative to the application root.

Result: CKFinder Misconfiguration

In both examples the parameters point to different server directories. As a result, some CKFinder features may not work correctly. The View function, for example, will be one of them.

Why is that so?

As mentioned above, CKFinder works on files and for this it uses the baseDir parameter value. All uploaded files will thus be placed in the location that is set in this parameter. HTTP clients, on the other hand, will use the baseURL value, but in both examples presented above this parameter will point to a non-existent location which in some cases may lead to a lack of access to files.

BaseDir and BaseUrl best practice

It is always recommended to set both baseUrl and baseDir so that they point to same location which is outside of an application directory.

In previous section, we have seen what problems we may get when these two properties are misconfigured but what will happen when only baseUrl is set? CKFinder needs both, baseUrl and baseDir to work correctly and if baseDir is missing, CKFinder will try to determine its value based on the baseUrl property. You must know however that CKFinder has limited capabilities in this case. To be more precise, CKFinder is mainly limited to application context (application main directory). Let’s have a look at few examples:

<baseURL>/userfiles/</baseURL>
<baseDir></baseDir>
<!--or-->
<baseURL>http://example.com/userfiles/</baseURL>
<baseDir></baseDir>

In both above cases the userfiles folder points to server’s main applications directory. When multiple applications are kept on server they are accessible like http://example.com/CKFinderJava-2.5 or http://example.com/CKFinderJava-2.4. As you can probably see the userfiles folder should be created on same level as applications in order to be accessible through HTTP. The problem is that applications folder is not accessible from the web. There are however two servers which have general accessible folders and to which CKFinder can get. These servers are Apache Tomcat and Oracle GlassFish. Having configuration like presented above, starting from CKFinder 2.5.1, CKFinder will create userfiles folder in TOMCAT_HOME/webapps/ROOT directory for Apache Tomcat and GLASSFISH_HOME/glassfish/domains/domain_name/docroot directory for Oracle GlassFish. Everything will work as expected in this case. For other supported servers, CKFinder will use fallback approach and create userfiles folder inside CKFinderJava application directory. As you probably know, this will unfortunately result in View option not working properly.

Let’s take a look at another example:

<baseURL>/CKFinderJava/userfiles/</baseURL>
<baseDir></baseDir>

Above setting will create userfiles inside CKFinderJava application directory. Although such configuration will work on every server there is a caveat to that approach. It isn’t recommended to put folder for uploaded files into deployed application folder because with every redeployment (e.g. when upgrading war to new version) of the application, the upload folder will be removed. So, what should be done to set baseUrl and baseDir correctly?

First of all you should set both properties so that they point to same location which is accessible through HTTP and from the file system. Second, you should set these properties to point to location outside of CKFinder application folder.

One solution is using symlinks. The userfiles folder located inside application context can be a symbolic link to some other directory on the disk. With that simple approach /CKFinderJava/userfiles/ can point to folder of your choice. One downside of this technique is that you have to recreate the symbolic link with every application redeploy as the symlink gets removed on redeployment.

Another solution is using server features. Most of the servers provide "virtual directory" mechanism. A "Virtual Directory" allows accessing through HTTP a folder which can be located even outside of the server. In Tomcat 7-8 this can be done through aliases, in Tomcat 6 by adding another context to server.xml, in GlassFish through alternate docroots, in Jetty by adding another context to jetty.xml, in Weblogic through virtual directories, in WildFly by adding extra entries to urn:jboss:domain:undertow subsystem element in one of configuration files e.g. standalone.xml and in JBOSS EAP by allowing symlinks for particular external folder in jboss-web.xml file and then making that symlink.

Let’s have a look at an example for Apache Tomcat 8. The server is installed in C:/Apache-Tomcat-8/ directory, CKFinderJava is installed in C:/Apache-Tomcat-8/CKFinderJava, we want to have our userfiles folder located directly on C drive and we want that folder to be called "myimages". Here are the settings that will allow having all CKFinder features working, and userfiles folder not being removed with every redeployment of the application:

CKFinder config.xml settings:

<baseDir>C:/myimages</baseDir>
<baseURL>/CKFinderJava/userfiles/</baseURL>

CKFinderJava/META-INF/context.xaml settings:

<Context antiJARLocking="true" path="/CKFinderJava" reloadable="true" >
    <Resources>
       <PreResources base="C://myimages" className="org.apache.catalina.webresources.DirResourceSet" webAppMount="/userfiles" />
   </Resources>
   <Valve className="org.apache.catalina.valves.RemoteAddrValve"  allow=".*" />
</Context>

With the help of the server and two configuration changes, you can have your files being saved to C:/myimages folder. It’s also worth mentioning that myimages directory is invisible to end user and Tomcat serves files as if they really were located inside CKFinderJava/userfiles/.