Changes

BaseX provides access to stored database resources and to This page is part of the XQuery engine via [[REST]], [[RESTXQGetting Started]] and [[WebDAV]] servicesSection. This article It describes different way of deploying and configuring these services. The services how BaseX can be deployed in 3 different ways: as a standalone application, as used to both provide simple APIs and build complex web servlets in a J2EE servlet container, and for development purposes, using mavenapplications.

=Standalone: BaseX HTTP ServerStartup=Detailed description how to start and setup the standalone BaseX HTTP server can found under [[Startup#BaseX HTTP Server|Startup: BaseX HTTP Server]] and [[Startup_Options#BaseX_HTTP_Server|Startup Options: BaseX HTTP Server]].

In order to deploy BaseX HTTP Services in a servlet container, one needs to download the WAR distribution Both an instance of BaseX from the [httphttps://basexwww.eclipse.org/productsjetty/download/all-downloads download siteJetty]. The downloaded WAR file can be then deployed following the instructions of the corresponding servlet container. There are two ways to access databases:* either a dedicated and BaseX [[Startup#BaseX_Server|database serverDatabase Server]] should will be manually started,* or the web application will access and store data on the local file system.The operation mode can be configured as explained further below.<br/><b>Note:</b> when the web application stores data in the local file system of the servlet container, then by By default it will use a separate directory as home directory. This is because, in many production environmentsJetty listens to the port 8080, and the servlet container runs as a dedicated user without a {{Mono[[Database Server|$HOME}} directory. However BaseX needs to store somewhere it's settings and dataDatabase Server]] is accessible on port 1984. This is whyAfter startup, even when running you can access a servlet container with a normal user (i.e. one which has a {{Mono|$HOME}} directory), the web application will not use by the default the settings stored in {{Mono|$HOMEplain HTML welcome page via http://.basex}} and will have a different set (or empty set) of databases than the one in the case of the standalone HTTP server. However, this behavior can be changed by manually setting the BaseX home directory to {{Mono|$HOME}}, in which case the web application will use the same databases as in the case of the standalone serverlocalhost:8080.

==Servlet Container Configuration==Configuring portUnless you have already chosen an admin password yet (e.g., context pathvia the Windows installer or a previous installation), etc. you can be done following do so by invoking the corresponding instructions of the used servlet container.{{Command|PASSWORD}} command on your terminal:

<pre>basexhttp -c PASSWORDBaseX [HTTP Server]...[main] INFO org.eclipse.jetty.util.log - Logging initialized @239ms to org.eclipse.jetty.util.log.Slf4jLog...HTTP STOP Server was started (port: 8081).HTTP Server was started (port: 8080).Password: _</pre> The Jetty logging level can be adjusted by adding the following properties to the start script: <pre lang="xml">-Dorg.eclipse.jetty.util.log.class=Configuring Available Servicesorg.eclipse.jetty.util.log.StdErrLog -D{classref}.LEVEL=DEBUG</pre> Various [[Command-Line_Options#HTTP Server|command-line options]] are available to simplify batch processing. The [[Start_Scripts|start script]] can be adjusted for individual purposes (e.g. if the default memory limit is too restrictive). BaseX can also be deployed as web servlet in a servlet container or with Maven: ==Servlet Container==To enable In order to deploy BaseX HTTP Services in a servlet container, you can download the WAR distribution of BaseX from the [https://basex.org/download download site], or disable compile it by calling <code>mvn compile war:war</code> in the <code>basex-api</code> directory. The WAR file can then be deployed following the instructions of the corresponding servlet container ([https://www.eclipse.org/jetty/documentation/current/quickstart-deploying-webapps.html Jetty], [https://tomcat.apache.org/tomcat-9.0-doc/deployer-howto.html Tomcat], etc.). You can configure the port, context path, etc. by following the instructions of the corresponding servlet container. This is needed if you want to replace the default URL path (e.g. http://localhost:8080/rest) with a custom one (e.g. http://localhost:8080/basex/rest). If you use Jetty (which is the default HTTP server of BaseX), the server configuration is defined in the provided services{{Code|jetty.xml}} file, which is stored in the {{Code|WEB-INF}} directory next to the {{Code|web.xml}}. For detailed configuration, refer to the [https://www.eclipse.org/jetty/documentation/current/jetty-xml-config.html Jetty Documentation]. To run on [https://tomcat.apache.org/ Apache Tomcat], start the Tomcat server and add any <code>*.war</code> distribution to deploy via the Tomcat web interface. By default, the interface is accessible via http://localhost:8080/manager/html/. ==Maven== Check out the BaseX sources via [[Developing with Eclipse|Eclipse]] or [[Git]]. Execute <code>mvn install</code> in the main project directory and then <code>mvn install jetty:run</code> in the <code>basex-api</code> subdirectory. This will start a Jetty instance in which the servlets will be deployed. The same options as in the case of deployment apply in a servlet container. In this case, however, there is no WAR archive. Instead, Jetty looks up all files in the corresponding directory <code>[https://github.com/BaseXdb/basex/tree/master/basex-api/src/main/webapp basex-api/src/main/webapp]</code>. Jetty and servlet entry options can be configured in the {{MonoCode|jetty.xml}} and {{Code|web.xml}} files as described above in the [[#Configuration|Servlet Container Configuration]]. The Jetty stop port can be changed in the [https://www.eclipse.org/jetty/documentation/current/jetty-maven-plugin.html Maven Jetty Plugin] sesion in the {{Code|pom.xml}} file needs . =Services= The following services are available and enabled by default: {| class="wikitable"|- valign="top"! Name! Standard Path! Description|- valign="top"| [[RESTXQ]]| <code>/</code>| Write enriched APIs and full web applications with XQuery.|- valign="top"| [[WebSockets]]| <code>ws/</code>| Bidirectional client/server communication.|- valign="top"| [[REST]]| <code>rest/</code>| Straightforward access to XML databases and its resources.|- valign="top"| [[WebDAV]]| <code>webdav/</code>| Database access via the file system.|- valign="top"| Default| <code>static/</code>| Access to static server resources (HTML, JavaScript, CSS, images, …).|} The [[DBA]] is a web-based database administration interface written in RESTXQ. It allows you to create and administrate databases, evaluate queries in realtime, view log files, manage users, etc. It is embedded in the full distributions of BaseX, and it can be removedaccessed after startup via http://localhost:8080/commenteddba/. =Configuration= Unless BaseX is deployed as servlet, the location of the web application directory can be adjusted via the {{Option|WEBPATH}} option, and compression of HTTP responses can be enabled via the {{Option|GZIP}} option. Further database options can be defined as context parameters in the {{Code|web.xml}} file. The most important options for the web application context are:

! width='70' "160" | Option! width="90" |Default

| {{MonoOption|org.basex.pathUSER}}| Path to the BaseX home directory, in which the {{MonoCode|.basexadmin}} configuration file will be placed. By default, no value | If a user is specified; as a result, no credentials must be passed on by the default servlet context path will be usedclient.

| {{MonoOption|org.basex.modeHTTPLOCAL}}| Operation mode. By default, the value is "{{MonoCode|localfalse}}": the servlets will access and store data locally using {{Mono|orgOperation mode.basex.path}}. If "{{Mono|client}}" is specifiedBy default, all operations are performed on a remote database server instance (will be started, as soon as the login data of which first HTTP service is stored in the called. The database server can be disabled by setting this flag to {{MonoCode|.basextrue}} configuration file).

| {{MonoOption|org.basex.userRESTXQPATH}}| Database user. By default, no value is specified, and the credentials must be specified by the client. Note that it is a clear security risk to store user credentials in the {{MonoCode|web.xml}} file. The default user credentials can be found under |Relative or absolute directory referencing the [[Startup#BaseX_Client|Startup: BaseX ClientRESTXQ]]modules. By default, the option points to the standard web application directory.

| {{MonoOption|orgRESTPATH}}|{{Code|.}}|Relative or absolute directory referencing queries and command-scripts that can be invoked via the [[REST#GET_Requests|run operation]] of REST.basexBy default, the option points to the standard web application directory.password|- valign="top"|{{Option|AUTHMETHOD}}|{{Code|Basic}}| Database user passwordThe default authentication method proposed by the server. The available methods are {{Code|Basic}} and {{Code|Digest}}.

All options are prefixed with {{Code|org.basex.}}. Local file paths in options may be absolute or relative. If a relative path is specified, its root will be the servlet’s ({{Code|webapp}}) path: <pre lang=Maven"xml"><context-param> <param-name>org.basex.dbpath</param-name> <!-- will be rewritten to ..../webapp/WEB-INF/data --> <param-value>WEB-INF/data</param-value></context-param><context-param> <param-name>org.basex.repopath</param-name> <!-- will be kept as is --> <param-value>f:/basex/repository</param-value></context-param></pre>  Context parameters can be requested from XQuery via [[Process_Module#proc:property-names|proc:property-names]] and [[Process_Module#proc:property|proc:property]]. How to set these options is specific to the servlet container. For example, in Jetty it can be done by [http://www.eclipse.org/jetty/documentation/current/override-web-xml.html overriding the web.xml] file. Another option is to directly edit the {{Code|WEB-INF/web.xml}} file in the WAR archive (WAR files are simple ZIP files). Refer to the sample [https://github.com/BaseXdb/basex/blob/master/basex-api/src/main/webapp/WEB-INF/web.xml web.xml] of the {{Code|basex-api}} package. To enable or disable a specific service, the corresponding servlet entry in the {{Code|web.xml}} file needs to be removed/commented. ==Authentication== No credentials need to be supplied if a default user is assigned to a service in the {{Code|web.xml}} file. In the following example, the user {{Code|rest-user}} is specified for the REST service: <pre lang="xml"><servlet> <servlet-name>REST</servlet-name> <servlet-class>org.basex.http.rest.RESTServlet</servlet-class> <init-param> <param-name>org.basex.user</param-name> <param-value>rest-user</param-value> </init-param></servlet></pre> If the HTTP server is started with no pre-defined user, the credentials must be passed on by the client via [https://en.wikipedia.org/wiki/Basic_access_authentication Basic Authentication] or [https://en.wikipedia.org/wiki/Digest_authentication Digest Authentication], depending on the chosen authentication method in the configuration. With cURL, internet browsers, and other tools, you can specify basic authentication credentials within the request string as plain text, using the format <code>USER:PASSWORD@URL</code>: : <code>http://admin:...@localhost:8080/</code> Users are specified in a {{Code|users.xml}} file, which is stored in the database directory (see [[User Management]] for more information). =Changelog= ;Version 10.0* Updated: The default admin password has been removed, and the default ports have been changed from 8984/8985 to 8080/8081. ;Version 9.0* Updated: <code>jetty.xml</code> configuration file (required for Jetty 9). ;Version 8.6* Updated: Authentication re-added to RESTXQ.* Updated: No password must be specified in the <code>web.xml</code> file anymore.* Updated: Server-side user and authentication method is now enforced (cannot be overwritten by client). ;Version 8.0* Added: digest authentication* Updated: user management* Updated: default user/password disabled in web.xml ;Version 7.7* Added: service-specific permissions

Checkout the sources of basex and basex-api as described under [[Integrate#Check_Out;Version 7.5* Added: {{Code|Integrate: Check Out]]jetty. Execute <code>mvn install</code> in the basex project folder and then <code>mvn install jettyxml}}:run</code> in the basex-api project folder. This will start a configuration for Jetty instance in which the servlets will be deployed.Server* Updated: {{Code|server}} replaced with {{Code|httplocal}} mode

==Configuration==;Version 7.3The same options as in the case of deployment in a servlet container apply. For configuring various Jetty runtime options, such as port, context path, etc. refer to the [http* Updated://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin Maven Jetty Plugin]. These should be entered in the {{MonoCode|pom.xmlclient}} file of the mode replaced with {{MonoCode|basex-apiserver}} project.mode