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 built on the cross-platform Kestrel web server for ASP.NET Core.

Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache.

Below are useful links to learn about installing and tuning ASP.NET Core applications in different 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 allows installing and uninstalling applications and configuring SSL certificates.

It supports configuring applications:

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 start the wizard and follow wizard steps.

If you installed ODataDB using the Windows installer package, you may open the ODataDB Setup link from the Windows Start.

The best choice is to configure the IIS website to use the following links to edit data in SQL Server, MySQL, and Postgres databases:

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

If you want just try ODataDB, start the console application and use HTTPs links:

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

or HTTP links (if the SSL certificate is not configured):

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

setup.exe has multiple useful modes to automate operations. Run setup /? to get help.

The wizard is available in multiple languages. By default, it uses the Windows UI language.

You may run the wizard with the required language using switches: /cn, /de, /en, /es, /fr, /hans, /hant, /it, /ja, /ko, /pt, /ru, /tw

Installing ODataDB on Windows

Installing steps:

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. For example, copy it to the C:\inetpub folder.
5. Add connection strings for your databases to the appsettings file.
6. Create an ODataDB application pool.
7. Create an ODataDB website or application.

Below are details for steps 6-7.

Creating ODataDB Application Pool

Open the IIS Manager, select Application Pools, and click the Add Application Pool... action to create an application pool.

Use the following values:

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

Creating ODataDB Website

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

In the last case, 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 the Add Website... action.

Then use the following values:

Note that it is important to choose the odatadb application pool created in the previous step.

To test the local website installation, open the URL:

http://odatadb/

You have to see the index page. Play with samples.

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

Configuring HTTPS Certificate on Windows

Do not use ODataDB over HTTP as browsers send logins and passwords as plain text.

Always turn on HTTPS and redirect HTTP to HTTPS.

Below are the steps to create a self-signed certificate.

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")

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

See more details here: 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 its bindings.
   Select HTTPS, click Edit..., and select ODataDB Certificate in the SSL Certificate list. Click OK.

To roll back the changes, restore the initial SSL certificate first and delete the ODataDB Certificate using the 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 on it, and click the Add Application... action.

Then use the following values:

Note that it is important to choose the odatadb application pool created in the previous step.

To test the localhost application, open the URL:

http://localhost/odatadb/

You have to see the index page. Play with samples.

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

Please note that ODataDB replaces the <base href="/"> line to <base href="/odatadb/"> for IIS applications automatically.

Installing ODataDB on Linux

See the complete guides here:

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

In short, make the following steps:

1. Install 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 change 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.

Below are details for steps 5-7.

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

Here is a complete 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, try to get data using a command like this:

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

Creating an odatadb subdomain

To create a subdomain, make the following steps:

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

Here is an Nginx configuration of 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