Skip to content

Create Site Command

The create command creates a new site on the Sites platform.

Overview

The create command allows you to: - Create sites from a YAML configuration file - Create sites using command-line flags - Specify templates for different site types - Set quotas and other site properties

Global Flags

All commands support these global flags:

  • --debug, -d, --verbose - Show debug information
  • --insecure, -k - Skip TLS certificate verification (insecure)
  • --force, -f, -y, --yes - Force operations without prompting
  • --output, -o - Output format: json, yaml, or table (default: table)

Command

sitesctl create

Create a new site using either a YAML configuration file or command-line flags.

Usage: 

sitesctl create [flags]

Flags:

  • --file - Path to site configuration file (YAML)
  • Type: String

  • If provided, other flags are ignored

  • --owner - Owner username

  • Type: String

  • Defaults to the authenticated user if not specified

  • --name - Site name

  • Type: String
  • Must be unique within the space

  • Lowercase alphanumeric and hyphens only

  • --space - Custom space name

  • Type: String
  • Defaults to the owner's username if not specified

  • Forms part of the site URL: https://sites.ecmwf.int/{space}/{name}

  • --template - Template name

  • Type: String
  • Examples: iver, jupyter, cms

  • Determines the initial site setup and features

  • --description - Site description

  • Type: String

  • Human-readable description of the site's purpose

  • --quota - Storage quota in GB

  • Type: Integer
  • Default: 1 GB

  • Determines maximum storage capacity for the site

  • --application - Application to enable on site

  • Type: String (repeatable)
  • Built-in applications: site-s3, site-webdav, site-admin
  • To disable an application, prefix with - (e.g., -site-admin)
  • The site-admin application is enabled by default; use --application -site-admin to remove it
  • Can be specified multiple times to enable/disable multiple applications

Examples:

# Create site from configuration file
sitesctl create --file mysite.yaml

# Create with force flag (no confirmation prompt)
sitesctl create --file mysite.yaml --force

Example YAML file (mysite.yaml): 

owner: myusername
site_name: myproject
custom_space: projects
description: "My project website"
template: iver
quota: 5
site_type: private
retention_date: "2027-12-31"

Creating with command-line flags

# Minimal site creation (uses defaults)
sitesctl create --name mysite --template iver

# Create with custom owner and space
sitesctl create --owner john --name website --space projects

# Create with all options
sitesctl create \
  --owner john \
  --name dataviewer \
  --space analytics \
  --template jupyter \
  --description "Data analysis notebooks" \
  --quota 10

# Create without confirmation prompt
sitesctl create --name mysite --template iver --force

# Create with applications
sitesctl create \
  --owner john \
  --name dataviewer \
  --template jupyter \
  --application site-s3 \
  --application site-webdav

# Create without site-admin (enabled by default)
sitesctl create \
  --owner john \
  --name mysite \
  --application -site-admin

# Create with S3 and without admin
sitesctl create \
  --owner john \
  --name datastore \
  --application site-s3 \
  --application -site-admin

What it does: - Validates the site configuration - Creates the site in the Sites Hub - Provisions storage backend - Sets up the web service - Returns the site details including the master token

Important Notes: - You must be authenticated (use sitesctl auth login) - Site creation may take a few moments - The command will prompt for confirmation unless --force is used - Master token is returned (save it securely for content operations)

Site Configuration

Required Parameters

When using command-line flags, you must provide at minimum: - --name - The site name

When using a YAML file, it must contain at minimum: - site_name - The site name

Site Name Requirements

Site names must: - Be unique within the space - Contain only lowercase letters, numbers, and hyphens - Start with a letter - Not end with a hyphen - Be between 1-63 characters

Valid names: - mysite - project-website - data2024

Invalid names: - MyProject (uppercase) - -mysite (starts with hyphen) - my_site (underscores not allowed) - site! (special characters not allowed)

Space Identifier

The space forms part of your site URL: 

https://sites.ecmwf.int/{space}/{name}

  • If not specified, defaults to the owner's username
  • Can be customized to group related sites
  • Must follow same naming rules as site names

Examples: - https://sites.ecmwf.int/john/mysite (space=john, name=mysite) - https://sites.ecmwf.int/projects/website (space=projects, name=website)

Templates

Templates provide pre-configured site types:

Template Description Use Case
iver Static website HTML/CSS/JS sites, documentation
jupyter JupyterHub Interactive notebooks, data science
cms Content Management Dynamic websites, blogs

Each template comes with: - Pre-installed software and dependencies - Default configuration - Appropriate runtime environment

Choosing a template: - Use iver for static content and simple websites - Use jupyter for interactive data analysis - Use cms for dynamic content management

Storage Quota

  • Specified in gigabytes (GB)
  • Default: 1 GB
  • Determines maximum storage for site content
  • Can be updated later with the update command
  • Check current usage with health commands

Recommendations: - Small websites: 1-2 GB - Documentation sites: 2-5 GB - Data-heavy sites: 10+ GB - Monitor usage and adjust as needed

YAML Configuration File

Using a YAML file is recommended for: - Complex site configurations - Reproducible site creation - Version control of site settings - Sharing site configurations

Complete YAML example: 

# Required fields
site_name: myproject
owner: myusername

# Optional fields
custom_space: projects
description: "Detailed description of the site purpose"
template: iver
quota: 5

# Site type (requires admin privileges)
site_type: private

# Retention date (YYYY-MM-DD)
retention_date: "2027-12-31"

# Access control (optional)
access_users:
  - user1
  - user2
access_groups:
  - group1

# Admin access (optional)
admin_users:
  - admin1
admin_groups:
  - admin-group

# Custom application settings (advanced)
custom_application_image: "eccr.ecmwf.int/myproject/myapp:1.0"
custom_application_context_root: "site_context"
custom_application_proxy: "proxy"
custom_application_extra_env:
  - "VAR1=value1"
  - "VAR2=value2"

YAML Field Reference:

Field Type Description
site_name String Site name (required)
owner String Owner username
custom_space String Space identifier
description String Site description
template String Template name
quota Integer Storage quota in GB
site_type String private or public (admin only)
retention_date String Retention date (YYYY-MM-DD)
access_users Array Users with access
access_groups Array Groups with access
admin_users Array Users with admin rights
admin_groups Array Groups with admin rights

Post-Creation Steps

After creating a site:

  1. Save the Master Token 

    # The token is displayed in the creation output
# Save it securely for content operations

  2. Configure Local Token (optional) 

    sitesctl auth site-token \
  --space myspace \
  --name mysite \
  --token <master-token>

  3. Upload Content 

    sitesctl site --space myspace --name mysite \
  content upload --source ./myfiles

  4. Verify Site Health 

    sitesctl site --space myspace --name mysite health

  5. Access Your Site 

    https://sites.ecmwf.int/{space}/{name}

Troubleshooting

Authentication Error

Error: Unauthorized
Solution: Login first with sitesctl auth login --username <username>

Name Already Exists

Error: Site name already exists in this space
Solution: Choose a different name or space

Invalid Name Format

Error: Invalid site name format
Solution: Use only lowercase letters, numbers, and hyphens

Insufficient Permissions

Error: You don't have permission to create sites
Solution: Contact your administrator for site creation privileges

Missing Required Fields

Error: No parameters provided to create the site
Solution: Provide either --file or at minimum --name and --template

Scripting Examples

Batch Site Creation

#!/bin/bash
# Create multiple sites from a list

sites=("site1" "site2" "site3")

for site in "${sites[@]}"; do
  sitesctl create \
    --name "$site" \
    --template iver \
    --quota 2 \
    --force
done

Create from Template with Timestamp

#!/bin/bash
# Create site with timestamped name

timestamp=$(date +%Y%m%d)
sitename="project-${timestamp}"

sitesctl create \
  --name "$sitename" \
  --template iver \
  --description "Created on $(date)" \
  --force

Create and Configure

#!/bin/bash
# Create site and immediately configure it

space="myspace"
name="mysite"

# Create site
sitesctl create --file site.yaml --force

# Extract and save token
token=$(sitesctl site --space "$space" --name "$name" tokens master-token show --output json | jq -r '.token')

# Configure local token
sitesctl auth site-token --space "$space" --name "$name" --token "$token"

# Upload content
sitesctl site --space "$space" --name "$name" content upload --source ./html

See Also