⚙️ Configuring SPACE

To launch SPACE, you need to provide a set of environment variables.
These variables define how the server, the client, and the supporting services (MongoDB, Redis) are configured.

Depending on your setup (local, Docker, or Kubernetes), the way to provide these variables changes — but the variables themselves remain the same.

---

🌐 Server Environment Variables

These variables configure the SPACE server:

Variable	Required	Default Value	Description
ALLOWED_ORIGINS	❌	*	Semicolon-separated string of allowed origins for CORS
DATABASE_NAME	❌	space_db	MongoDB database name (ignored if MONGO_URI is set)
DATABASE_USERNAME	❌	mongoUser	MongoDB username (ignored if MONGO_URI is set)
DATABASE_PASSWORD	❌	mongoPassword	MongoDB password (ignored if MONGO_URI is set)
MONGO_URI	❌	mongodb://${dbCredentials}localhost:27017/${dbName}	Full MongoDB connection string. dbCredentials correspond to the formatted version of DATABASE_USERNAME and DATABASE_PASSWORD, and dbName corresponds to DATABASE_NAME
REDIS_URL	✅	—	Redis URL for caching
JWT_SECRET	✅	—	Secret key for JWT generation. It can be any random string.
JWT_SALT	✅	—	Salt for JWT hashing. It can be any random string.
JWT_EXPIRATION	❌	1h	JWT expiration (e.g., 1d, 2h)
ADMIN_USER	❌	admin	Default admin username
ADMIN_PASSWORD	❌	space4all	Default admin password

---

🖥️ Client Environment Variables

These variables configure the SPACE client:

Variable	Required	Description
VITE_ENVIRONMENT	✅	development or production
VITE_SPACE_BASE_URL	✅	Base URL of the SPACE server. For example: http://space-instance:5403
VITE_SPACE_ADMIN_API_KEY	⚠️ Only in dev	API key for admin access (only works in development)

---

🚀 How to Provide Environment Variables

The way to configure SPACE depends on the technology you use.
Select your setup below:

🐳 Docker (>=SPACE@1.2.0)

🐳 Docker Setup

warning

This documentation applies to SPACE version 1.2.0 and later. If you're using an older version, please refer to the previous Docker setup instructions.

1. Locate the .env.template file in the root of the repository
2. Create a .env file based on it:

cp .env.template .env

3. Adjust the variables according to your setup

📦 Environment Variables

All variables follow the standard .env format:

KEY=value

important

All environment variables not defined in the .env will be set to their default, so only instanciate those you want to override.

Variable	Default Value	Description
BASE_PATH	/space	Base URL path
ADMIN_USER	admin	Default admin username
ADMIN_PASSWORD	space4all	Default admin password
ALLOWED_ORIGINS	http://localhost:3000;https://myapp.com	CORS origins (semicolon-separated)
DATABASE_NAME	space_db	Database name (ignored if MONGO_URI is set)
DATABASE_ROOT_USERNAME	root	MongoDB root user
DATABASE_ROOT_PASSWORD	4dm1n	MongoDB root password
DATABASE_USERNAME	mongoUser	Application DB user (ignored if MONGO_URI is set)
DATABASE_PASSWORD	mongoPassword	Application DB password (ignored if MONGO_URI is set)
MONGO_URI	mongodb://user:pass@mongodb:27017/db	Full MongoDB URI
REDIS_URL	redis://redis:6379	Redis connection
JWT_SECRET	my_secret	JWT signing secret
JWT_SALT	random_salt	JWT hashing salt
JWT_EXPIRATION	1h	Token lifetime (1h, 1d, etc.)
ENVIRONMENT	production	Frontend environment
SPACE_HOST	http://localhost:5403	Public API URL

Important Notes

• Do not define environment variables inside docker-compose.yml anymore
• The .env file is now the single source of truth for configuration
• Server and client variables remain unchanged; only the injection mechanism differs
• Override sensitive values (e.g., JWT_SECRET, database credentials) in production

🐳 Docker (<SPACE@1.2.0)

🐳 Docker Setup

When using Docker, SPACE already ships with a minimal set of default environment variables.
You can override them or add new ones in docker-compose.yml:

• Server variables → under the environment section of the space-server service
• Client variables → under the environment section of the space-client service
• MongoDB & Redis → also configurable under their respective services, using the standard variables from their public images

💡 Example:

services:
  ...
  space-server:
    ...
    environment:
      ENVIRONMENT: production
      ALLOWED_ORIGINS: http://localhost:3000
      MONGO_URI: mongodb://user:password@mongodb:27017/space_db
      REDIS_URL: redis://redis:6379
      JWT_SECRET: test_secret
      JWT_SALT: mySalt
      JWT_EXPIRATION: 1d
  space-client:
    ...
    environment:
      VITE_ENVIRONMENT: production
      VITE_SPACE_BASE_URL: http://localhost:5403/api/v1
  ...

💻 Local Development

💻 Local Development

If you run SPACE locally without Docker/Kubernetes:

• Create a .env file inside /api → server variables
• Create a .env file inside /frontend → client variables

💡 Example of /api/.env:

ENVIRONMENT=development
# ---------- CACHE CONFIGURATION (Redis) ----------

REDIS_URL=redis://localhost:6379

# ---------- JWT CONFIGURATION ----------

JWT_SECRET=test_secret
JWT_SALT=mySalt
JWT_EXPIRATION=1d

# ---------- DEFAULT USER CONFIGURATION ----------

ADMIN_USER=admin
ADMIN_PASSWORD=adminPassword

💡 Example of /frontend/.env:

VITE_ENVIRONMENT="development"
VITE_SPACE_BASE_URL=http://localhost:3000/api/v1
VITE_SPACE_ADMIN_API_KEY=9cedd24632167a021667df44a26362dfb778c1566c3d4564e132cb58770d8c67
# ⬆️ (Only in development) API key for admin access

☸️ Kubernetes (alfa)

☸️ Kubernetes Setup

When using Kubernetes, default environment variables are already defined in:

• Server → k8s/config/server-config.yml
• Client → k8s/config/client-config.yml

You can edit these files to add/override variables.

💡 Example k8s/config/server-config.yml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: server-config
data:
  ENVIRONMENT: production
  JWT_EXPIRATION: 1d
  JWT_SALT: mySalt
  JWT_SECRET: test_secret
  MONGO_URI: mongodb://user:password@mongodb-service:27017/space_db
  REDIS_URL: redis://redis-service:6379

MongoDB & Redis Configuration

MongoDB and Redis can also be configured via their manifests in k8s/config, using the variables defined in their official images.

warning

Since SPACE images are not yet published on Docker Hub, they must be built locally. When doing so, remember to configure the ALLOWED_HOST environment variable for the space-server service in the Docker Compose configuration, as well as the VITE_SPACE_BASE_URL environment variable for the space-client.