Installing ODataDB

Table of Contents

• Platform Details
• Installing ODataDB on Windows Using Setup Wizard
• Installing ODataDB on Windows
• Installing ODataDB on Linux

Platform Details

ODataDB is an ASP.NET Core application running on the cross-platform Kestrel web server for ASP.NET Core.

Kestrel can operate independently or alongside a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache.

Here are some useful links for installing and tuning ASP.NET Core applications in various scenarios:

• Host ASP.NET Core on Windows with IIS
• Host ASP.NET Core on Linux with Nginx
• Host ASP.NET Core on Linux with Apache
• Kestrel web server implementation in ASP.NET Core

Installing ODataDB on Windows Using Setup Wizard

The ODataDB setup wizard simplifies the installation and uninstallation of applications and the configuration of SSL certificates.

It supports configuring applications as:

1. IIS website
2. IIS application
3. Windows service
4. Console application for .NET
5. Console application for .NET Framework

Run odatadb\setup.exe to launch the wizard and follow the prompts.

If you installed ODataDB using the Windows installer package, you can access the ODataDB Setup link from the Windows Start menu.

For optimal performance, configure the IIS website to use the following links for editing data in SQL Server, MySQL, and PostgreSQL databases:

• https://odatadb/edit/mssql/
• https://odatadb/edit/mysql/
• https://odatadb/edit/pgsql/

If you want to test ODataDB, start the console application and use the following HTTPS links:

• https://localhost:5002/edit/mssql/
• https://localhost:5002/edit/mysql/
• https://localhost:5002/edit/pgsql/

Alternatively, use HTTP links if the SSL certificate isn't configured:

• http://localhost:5002/edit/mssql/
• http://localhost:5002/edit/mysql/
• http://localhost:5002/edit/pgsql/

The setup.exe has several modes for automating operations. Run setup /? for help.

The wizard supports multiple languages, defaulting to the Windows UI language. You can specify a language using the following switches: /cn, /de, /en, /es, /fr, /hans, /hant, /it, /ja, /ko, /pt, /ru, /tw.

Installing ODataDB on Windows

Follow these steps to install ODataDB:

1. Enable IIS on your machine.
2. Install the .NET Core Hosting Bundle.
3. Restart IIS.
4. Copy the odatadb subfolder from the ODataDB download package to your local drive, e.g., C:\inetpub.
5. Add connection strings for your databases to the appsettings file.
6. Create an ODataDB application pool.
7. Create an ODataDB website or application.

Details for steps 6 and 7 are below.

Creating ODataDB Application Pool

Open IIS Manager, select Application Pools, and click Add Application Pool... to create a new application pool.

Use the following values:

• Name: odatadb
• .NET CLR version: No Managed Code
• Managed pipeline mode: Integrated

Creating ODataDB Website

Use this scenario to create a subdomain like odatadb.contoso.com or a local domain like odatadb for access via https://odatadb/.

For the local domain, add the following line to the c:\windows\system32\drivers\etc\hosts file:

127.0.0.1 odatadb

To create the website, select the Sites node and click Add Website....

Use the following values:

Ensure you select the odatadb application pool created earlier.

To test the local website installation, open the URL:

http://odatadb/

You should see the index page. Explore the samples.

For example, try the cashbook table from the mssql-023 sample hosted in an online SQL Server database:

Configuring HTTPS Certificate on Windows

Avoid using ODataDB over HTTP, as browsers transmit logins and passwords in plain text.

Always enable HTTPS and redirect HTTP to HTTPS.

To create a self-signed certificate, follow these steps:

1. Open Windows PowerShell (Admin) and execute the command:

New-SelfSignedCertificate -NotBefore (Get-Date) -NotAfter (Get-Date).AddYears(5) -DnsName "localhost", "odatadb" -KeyAlgorithm "RSA" -KeyLength 2048 -HashAlgorithm "SHA256" -CertStoreLocation "Cert:\LocalMachine\My" -KeyUsage KeyEncipherment -FriendlyName "ODataDB Certificate" -TextExtension @("2.5.29.19={critical}{text}","2.5.29.37={critical}{text}1.3.6.1.5.5.7.3.1")

This creates a self-signed certificate for the localhost and odatadb hosts.

For more details, see: New-SelfSignedCertificate.

1. Open certlm.msc and copy the ODataDB Certificate from the Personal Certificates store to Trusted Root Certification Authorities.

2. Open IIS Manager, select Default Web Site, and edit its bindings.
   Select HTTPS, click Edit..., and choose the ODataDB Certificate from the SSL Certificate list. Click OK.

To revert changes, restore the initial SSL certificate and delete the ODataDB Certificate using certlm.msc.

Creating ODataDB Application

Use this scenario to create an application like www.contoso.com/odatadb/ or localhost/odatadb/.

To create an application, select the desired website node, right-click, and click Add Application....

Use the following values:

Ensure you select the odatadb application pool created earlier.

To test the localhost application, open the URL:

http://localhost/odatadb/

You should see the index page. Explore the samples.

For example, try the s02_cashbook table from the mssql-023 sample hosted in an online SQL Server database:

Note that ODataDB automatically replaces the <base href="/"> line with <base href="/odatadb/"> for IIS applications.

Installing ODataDB on Linux

Refer to the complete guides here:

• Host ASP.NET Core on Linux with Nginx
• Host ASP.NET Core on Linux with Apache

In summary, follow these steps:

1. Install the ASP.NET Core Runtime 8.0.
2. Copy the odatadb subfolder from the ODataDB download package to the /var/www folder.
3. Add connection strings for your databases to the appsettings file.
4. Check or modify the default Kestrel ODataDB port (5002) in the appsettings file.
5. Create a service file to manage the Kestrel process and enable the service.
6. Create an odatadb subdomain.
7. Configure an HTTPS certificate.

Details for steps 5-7 are below.

Creating a service file to manage the Kestrel process and enabling the service

Refer to this guide: Create the service file.

We recommend creating the /etc/systemd/system/kestrel-odatadb.service file with the following content:

[Unit]
Description=odatadb

[Service]
WorkingDirectory=/var/www/odatadb
ExecStart=/usr/bin/dotnet /var/www/odatadb/odatadb.dll
Restart=on-failure
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-odatadb
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

After creating the file, enable and start the service:

sudo systemctl enable kestrel-odatadb.service
sudo systemctl start kestrel-odatadb.service
sudo systemctl status kestrel-odatadb.service

To test the service, use a command like:

curl http://localhost:5002/v4/mssql-023/cashbook

Creating an odatadb subdomain

To create a subdomain, follow these steps:

1. Create the DNS A record for your domain.
2. Add a subdomain section to your domain configuration file.

Here’s an example Nginx configuration for the odatadb.savetodb.com subdomain:

server {

    server_name odatadb.savetodb.com;

    location / {
        proxy_pass         http://localhost:5002;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Configuring an HTTPS certificate on Linux

We recommend reading this resource: Secure HTTP Traffic with Certbot.