baseDir and baseURL Parameters Explained

This website contains links to software which is either no longer maintained or will be supported only until the end of 2019 (CKFinder 2). For the latest documentation about current CKSource projects, including software like CKEditor 4/CKEditor 5, CKFinder 3, Cloud Services, Letters, Accessibility Checker, please visit the new documentation website.

If you look for an information about very old versions of CKEditor, FCKeditor and CKFinder check also the CKEditor forum, which was closed in 2015. If not, please head to StackOverflow for support.

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-X.Y/userfiles/</baseURL>
    <baseURL>/CKFinderJava-X.Y/userfiles/</baseURL>
  • baseDir gives an absolute path to the directory on the server (a physical machine). For example:
    <baseDir>/usr/tomcat/webapps/CKFinderJava-X.Y/userfiles/</baseDir>
    <baseDir>C:\tomcat\webapps\CKFinderJava-X.Y\userfiles\</baseDir>
important note

Note that X.Y in the code above denotes a CKFinder version, like 2.0.


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-X.Y/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-X.Y/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.

More on baseURL

As stated above, if the baseDir parameter is empty, CKFinder will try to deduce the userfile path based on the baseURL parameter value.

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

If the server hosts more applications for one domain (like localhost or www.example.com), the code above will not work for most of them. To be exact, it will work only for the application that is set as the default one for the domain.

This may sound a bit enigmatic, but here is the explanation.

If the server hosts multiple applications in one domain, the users usually call them in the following way (note this does not pertain to the default application):

http://localhost:8080/CKFinderJava-X.Y/
http://www.example.com/CKFinderJava-X.Y/

or the following way, where filemanager is the context path for the CKFinderJava-X.Y application:

http://localhost:8080/filemanager/
http://www.example.com/filemanager/

These applications are (physically) located in one directory (like webapps for Tomcat or Jetty) and to differentiate between them, the user needs to include the name or alias (context path) of the called application in its URL. When the baseURL parameter is set to point directly to the userfiles folder, CKFinder will create this folder in the application directory (like CKFinderJava-X.Y/userfiles/). On the other hand, when the user will want to use the View option, the browser will search for the image in the http://localhost:8080/userfiles/ directory (http://hostName/baseURL/) instead of http://localhost:8080/CKFinderJava-X.Y/userfiles/.

The first address points to the userfiles directory placed in the root of the web applications directory. Since the CKFinder userfiles directory is located elsewhere, the image will not be found and the browser will display the "404 — Not found" error.

It is worth noting that the example above will work if you set one of the applications as a default for a domain (for example by using virtual hosting). Do remember, though, that this is only possible for one application per domain. With this configuration in place the userfiles directory will be created in the application root, but by default the application root is associated with the domain name, so calling http://localhost:8080/userfiles/ will let you search in the CKFinderJava-X.Y application folder and display the image.