Dataspecer

A set of tools for effortless management and creation of data specifications.

Check our website dataspecer.com for more information.

Docker container

You can easily run the whole application in a Docker container.

If you just want to try it out for a while and don't care where the data is stored, use following command and then go open http://localhost:3000/.

docker run -it --rm -eBASE_URL=http://localhost:3000/ -p3000:80 ghcr.io/dataspecer/ws

---

• The container exposes port 80.
• Mount /usr/src/app/database directory to your local directory that will be filled with database.db file and stores directory. If the directory is empty, files would be created. You need to mkdir the mounted directory with the correct user otherwise Docker will create it as root.
• If you want to run the Dataspecer under specific user, use USER env variable with desired UID.
• You MUST specify full base URL using BASE_URL env. Some functionalities need to know the domain name and the relative subdirectory is also important. If you are using reverse proxy, it is expected that the base path is preserved. (For example, https://example.com/dataspecer-instance-1/schema should point to http://localhost:3001/dataspecer-instance-1/schema)

Use the following docker run command:

docker run -it --name dataspecer -eBASE_URL=http://localhost/ -eUSER=1000 -v ./database:/usr/src/app/database -p80:80 ghcr.io/dataspecer/ws

Or use following docker-compose file

services:
  dataspecer:
    image: ghcr.io/dataspecer/ws
    environment:
      BASE_URL: http://localhost
      USER: 1000
    ports:
      - 80:80 # Change the first number to your desired port
    volumes:
      - ./database:/usr/src/app/database
      #- ./main.config.js:/usr/src/main.config.js # Backend configuration

Documentation

Check what to learn - a simple guide on how to start working on the project.

How to build locally

This repository is a monorepo - consisting of several packages, applications, and services that are build and developed separately, but depends on each other.

For more information about individual packages, applications, and services, please see the given directory. Each contains a README.md file with build instructions and additional documentation.

• applications - web clients
• packages - core and helper packages and individual generators
• services - backend service (used by both web and cli clients)

The monorepo is managed by npm workspaces and Turborepo. Please see the individual packages for their build instructions.

You can check the Cloudflare's build script that deploys all applications. We use Cloudflare Pages for that. Any commit pushed to GitHub into the repository is automatically built, and changes are deployed to the internet. Commits to other branches are also deployed as previews.

In general

Your node -v should be at least v18.19.0, but v20 is recommended.

After cloning the repository you should create local config files. Please see individual applications or packages what to do.

Then

• Run npm install to install all external packages (including TypeScript for typechecking and Turborepo for building) and link all dependencies between local packages.
• Run npm run build to build everything. This will execute turbo build under the hood. This will build packages, which are necessary for the development of other packages and applications; and it also build applications themselves, which is not necessary for development (see the next step). (If you want to build only packages necessary for a specific package or application, use npx turbo run build --filter=<package-name>. Obtain the name of the package from package.json file.)

To develop a concrete package or application, there is usually an npm run dev script that will run live server, which updates everything. See individual packages for more details.

Inside Docker