archiyou-server

This repository contains the Archiyou server backend. This will enable you to host the archiyou platform on your own servers.

It has:

• publish: Serve archiyou CAD scripts (default in ./scripts/) through REST API and execute them. This is the functionality to serve the configurators with data and do simple (pre)caching
• [TODO] editor backend: Saving script (versions) while using the editor. This includes a datastore, simple authentication etc.

Stack

• Node 22+
• Redis for task queue
• BullMQ for task manager and workers
• Fastify for simple REST API and simple auth with JWT tokens (<5 now for Node 18 )
• archiyou-core - Archiyou script execution used as npm module
• Some examples scripts.

Basic components

• Library - Manages local scripts (and their versions) on disk
• REST API - Takes requests for scripts or script executions
• ExecutionBroker - Places any execution request on Redis/BullMQ queue
• Worker + ExecutionWorker - Takes request from queue and executes

Setup

Create a .env file with these variables and your values:

LIBRARY_PATH=./scripts
LIBRARY_URL=http://localhost:4000
REDIS_HOST=localhost
REDIS_PORT=6379
# set own passwords for production:
REDIS_PASW=XXXXXXXX
ADMIN_PASSWORD=my_own_admin_pasw
# Generate a string with 64 chars
JWT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# if you want to use external conversion services (like we have)
SERVICES_API_URL=http://localhost:8090

Development

# install dependencies
pnpm install
# or npm, yarn, bun etc

# run unit and integration tests
pnpm test
# NOTE: you need docker for integration tests!
# if all tests pass you are ready to go!

We mostly develop with a test-driven approach. Starting with simple tests. See ./tests/unit and ./tests/integration and develop something until it works. You can use something like pnpm vitest run ./tests/units/{{myfeature}}.test.ts to run a specific test file.

To start entire development (API, queue and worker) stack:

docker compose up # start development stack
# or for the same
pnpm docker:api:dev

You can access it at http://localhost:4000/.

Production

Archiyou uses this stack in production. Caddy is added as SSL certicate manager/proxy.

# for production stack (which includes Caddy for SSL/proxy)
docker compose -f docker-compose.prod.yml
# or 
pnpm docker:api:prod

Please check any open ports, pasword values in env before hosting on the web!

REST API

The API has the following endpoints:

• /scripts [GET] - get scripts in library
• /scripts/{author} [GET] - Get scripts in library by author (example: http://localhost:4000/scripts/archiyou)
• /scripts/{author}/{scriptname}:{?version} - get script (example: http://localhost:4000/scripts/test/testbox)
• For getting scripts you can omit /scripts as shortcut http://localhost:4000/scripts/archiyou works too!
• /{author}/{script}:{version} [POST] - execute script with JSON payload. For example http://localhost:4000/test/testbox

  {
      "params": {
          "size" : 15
      },
      "outputs" : ["default/model/glb"],
      "cache" : false,
      "forceFileResponse" : true
  }

• /auth/login [POST] - for admin
• [TODO] /scripts/publish [POST] - publish script to library from the web
• [TODO] /scripts/unpublish [POST] - publish script to library from the we

Licence

Apache2