Skip to main content

Project Setup

After installing the Oidis Builder, you're ready to set up a project. This guide covers cloning, dependency installation, database setup, and IDE configuration.

Prerequisites​

ToolVersionPurpose
Node.jsLTS (18+)JavaScript runtime
npmBundled with Node.jsPackage manager
GitLatestVersion control
MongoDB6.0+Database (local or Docker)
IntelliJ IDEAUltimate recommendedPrimary IDE
Oidis BuilderLatestBuild toolchain (Installation Guide)
ToolPurpose
DockerRunning MongoDB and CI builds locally
Bootstrap StudioVisual UI panel design (.bsdesign files)
MongoDB CompassGUI for database inspection

Step 1: Clone the Repository​

# Clone the project
git clone git@gitlab.com:oidis/solutions/io-oidis-yourproject.git
cd io-oidis-yourproject

# Switch to develop branch
git checkout develop

Oidis dependencies are listed in package.conf.jsonp as git URLs. The Builder handles cloning them into the dependencies/ directory during installation.

Step 2: Install Dependencies​

oidis install

This command:

  1. Reads package.conf.jsonp
  2. Resolves extendsConfig and imports chains
  3. Clones Oidis dependencies (git repos) into dependencies/
  4. Generates package.json, tsconfig.json, webpack.config.js
  5. Runs npm install for npm dependencies

The ForceCompile.ts generated block is not part of install — every build adds the files containing @Extern(, @Resolver( or @Route( to it.

First run takes longer

The initial oidis install clones all dependency repos. Subsequent runs are faster as they only update.

Step 3: Configure MongoDB​

Oidis projects use MongoDB. The default development configuration (in bin/project/configs/commons.jsonp) typically expects:

Host: localhost
Port: 27017 (or project-specific, e.g., 27018)
Database: IoOidis[ProjectName]Dev

Option A: Local MongoDB​

Install MongoDB Community Edition and start the service. Create the database on first application start (MongoDB creates it automatically).

Option B: Docker​

docker run -d \
    --name oidis-mongo \
    -p 27017:27017 \
    mongo:6.0

Check your project's commons.jsonp for the exact port and database name.

Step 4: IDE Setup (IntelliJ IDEA)​

For detailed IDE configuration, see the IDE Configuration guide.

Quick setup:

  1. File → Open → Select the project root directory
  2. IntelliJ should detect the tsconfig.json and configure TypeScript automatically
  3. Import code style from Oidis_TypeScript_lint.xml (available from hub.oidis.io)
  4. Set TypeScript version to the project's node_modules/typescript

Step 5: Verify the Setup​

Run the linter to confirm everything is connected:

oidis.cmd project-cleanup test:lint

If this passes without errors, your environment is ready.

Step 6: First Build​

oidis rebuild

This compiles TypeScript, processes SCSS, and bundles the frontend. See First Build for details on what happens during the build process.

Troubleshooting​

"Cannot find module" errors​

Run oidis install again — dependencies may not have been fully resolved.

MongoDB connection refused​

Check that MongoDB is running and the port matches your commons.jsonp configuration.

Git authentication failures during install​

The Builder clones dependencies via git. Ensure your SSH key or git credentials are configured for GitLab access.

Generated files out of date​

If tsconfig.json or package.json seem wrong, delete them and run oidis install to regenerate.

Next: Understand the Project Structure and learn what each directory contains.

See also: Project Structure | Installation Guide