VocaDB development environment (Windows)

Requirements

• OS: Windows 10, Windows Server 2012 R2 or newer
• RAM: 1GB for the site, 4GB or so for the database
• Microsoft SQL Server 2012 or newer (can be made to run on 2010 with some code changes). SQL Server 2012 SP2 or newer recommended. SQL Server Express and LocalDB should work too.
• Visual Studio 2019 (free Community version is enough)
  • 16.9 or newer
  • Workloads:
    • ASP.NET and web development
    • .NET desktop development
• Visual Studio Code
  • Extensions:
    • ESLint
    • Prettier - Code formatter
• IIS or IIS Express
  • Static files support
• .NET 7 SDK. or higher
• Node.js v12.18.3 (or latest LTS) with NPM.

Step-by-step first setup

1. Ensure you have all the requirements installed.

2. Clone the repository and its submodules.

   git clone https://github.com/vocadb/vocadb.git --recurse-submodules
   cd vocadb

3. Open the VocaDB project on Visual Studio.

4. Prepare the configuration files. See web.config section for more information.

5. Prepare the database. See Database configuration section for more information.

   1. Open SQL Server Management Studio and log in to your SQL Server instance.

   2. Create a database with the name VocaloidSite.

      1. Right click Databases on the Object Explorer and press New Database….
      2. On Databse name:, write VocaloidSite.
      3. Switch to the General page by clicking 🔧 Options on the right.
      4. On Collation:, ensure that it has CI on it. The <default> may be appropriate should your default collation has CI on it (how to check it). If it isn’t, you can choose either SQL_Latin1_General_CP1_CI_AS or Latin1_General_CI_AS.
      5. On Compabillity level:, ensure that is SQL Server 2012 (110) or higher (on the number in the brackets).
      6. Press OK on the bottom to create the database.

   3. Run the schema creation script against the database.

      1. Either download open the file on SQL Server Management Studio, or right click VocaloidSite, select New Query, and paste the whole file to it.
      2. Ensure VocaloidSite is selected on the Available Databases dropdown.
      3. Press the ▶ Execute button.

   4. Back to Visual Studio, build/compile the migrations by building VocaDb.Migrations (right click VocaDb.Migrations and press Build)

   5. Run the Package Manager console using the menu bar: Tools > NuGet Package Manager > Package Manager Console

   6. Using the Package Manager Console, install the dotnet-fm tool.

      dotnet tool install -g FluentMigrator.DotNet.Cli

   7. Using the Package Manager Console, execute the migration.

      dotnet-fm migrate -p sqlserver -c "Data Source=.; Initial Catalog=VocaloidSite; Trusted_Connection=True; Encrypt=False;" -a "VocaDb.Migrations/bin/debug/net472/vocadb.migrations.dll"

      You may adjust the connection strings so what is written here and on \VocaDbWeb\connections.config is the same.

      For more information, see Starting with FluentMigrator.

6. Build the frontend using Node.js. See Compiling frontend assets section for more information.

   1. Right click VocaDbWeb on the Solution Explorer in the right and select the Open in Terminal option.
   2. Install dependencies by running npm install on the Terminal.
   3. Build assets by running npm run production on the Terminal.

7. Run the server using Visual Studio.

   1. Select the VocaDbWeb startup item. Locate the ⚙ VocaDb… button on the top part of the window, and press the dropdown on the right of the button.
   2. Press ▶ IIS Express right beside the previous button to build/compile and run the server.

Formatting

Line endings and indentation are configured by EditorConfig. There’s a plugin for almost any major IDE/text editor. Please install that plugin before editing the code files.

For the frontend located on VocaDbWeb, Prettier and ESLint is used to ensure code quality. You can use plugins to enhance the use of them.

web.config

The main web.config refers to additional configuration files which contain sensitive settings such as passwords and connection strings. These files are: appsettings.config, connections.config (connection strings), machinekey.config (can be an empty machinekey element) and smtp.config (for SMTP settings). These configuration files are NOT in the version control because of their sensitive contents. You’ll have to create them yourself, with the relevant settings.

<?xml version='1.0' encoding='utf-8'?>
<appSettings>
    <add key="ConnectionStringName" value="Local" />
    <!-- Host address of the site. Appended to absolute URLs. May be HTTP or HTTPS -->
    <add key="HostAddress" value="http://localhost:39390" />
    <!-- Host address used for login or otherwise when SSL should be used. -->
    <add key="HostAddressSecure" value="http://localhost:39390" />
    <add key="StaticContentPath" value="C:\VocaDB-data\" />
    <add key="StaticContentHost" value="http://localhost:39392/vdbstatic" />
    <add key="StaticContentHostSSL" value="http://localhost:39392/vdbstatic" />
    <add key="TwitterConsumerKey" value="(Your Twitter Consumer Key goes here)" />
    <add key="TwitterConsumerSecret" value="(Your Twitter Consumer Secret goes here)" />
    <!-- Test recaptcha key so that the /User/Create page works properly. -->
    <add key="ReCAPTCHAPublicKey" value="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" />
    <add key="ReCAPTCHAKey" value="6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe" />
</appSettings>

<?xml version='1.0' encoding='utf-8'?>
<connectionStrings>
    <!-- Use IIS AppPool -->
    <add name="Local" connectionString="Data Source=.; Initial Catalog=VocaloidSite; Trusted_Connection=True;" />
</connectionStrings>

<?xml version='1.0' encoding='utf-8'?>
<machineKey />

<?xml version='1.0' encoding='utf-8'?>
<smtp />

Web server (IIS) configuration

Make sure you give write permissions to the web folder for whatever account you’re using for running the site (such as your own user account or IIS AppPool (recommended if running in IIS)).

You’ll need to enable the DELETE and OPTIONS (for CORS) verbs for IIS/IIS express: see here how.

Database configuration

You’ll need to create an empty database called VocaloidSite by default, but the name can be anything. For the compability level, it should be should be at least SQL Server 2012 (110). For the collation, it could be anything that is case insensitive (has CI on the name).

Then, download the schema creation script and run it against that database.

Finally, run migrations from the VocaDb.Migrations assembly using FluentMigrator.

Compiling frontend assets

Ensure Node.js is installed and VocaDbWeb is opened on the Terminal of Visual Studio Code (or Visual Studio) before running these commands.

Install the frontend dependencies by running this command.

npm install

Run this command so that Vite will automatically recompile your assets when it detects a change.

npm run dev

In some cases, you need to build it first so that the changes will be reflected on the website.

npm run build