---
title: Access & Repository Setup | Shopware Community Hub
description: >-
  Learn how to set up proper access credentials, repository structure, and
  choose the right scaffolding approach for your PaaS Shopware project.
canonical_url: 'https://hub.shopware.com/learn/unit/paas-access-repository-setup'
---

# Access & Repository Setup

<LearningObjectives>

- Configure secure access credentials and tokens for PaaS platforms.
- Set up a proper repository structure using Shopware templates or custom scaffolding.
- Understand directory organization and configuration file management.
- Implement security best practices for credential management.

</LearningObjectives>

# Access & Repository Setup

In this learning unit, you'll learn how to securely configure your development environment and establish a robust project foundation. We'll cover everything from setting up secure access credentials to choosing the right repository structure for your specific needs.

## Account, Token & Credential Management

Secure credential management is the foundation of any successful PaaS deployment. This section covers everything you need to establish proper access controls and maintain security best practices throughout your project lifecycle.

### Platform Access Setup

Before deploying your Shopware application, you must establish secure access credentials. While the specific implementation varies by platform, the underlying security principles remain consistent across all PaaS providers.

#### Initial Platform Authentication

Start by authenticating with your PaaS platform:

```bash
# Install PaaS CLI
curl -sfS https://cli.shopware.com/installer | php

# Authenticate with your Shopware PaaS account
shopware project:auth:login

# Verify successful authentication
shopware whoami
```

#### API Token Generation and Management

Most PaaS platforms, including Shopware PaaS, use API tokens for programmatic access and CI/CD integration:

```bash
# Generate a new API token for programmatic access
shopware project:auth:api-token-login

# List existing tokens
shopware project:auth:token:list

# Create a token with specific permissions
shopware project:auth:token:create --name "CI/CD Token" --scopes "project:read,environment:write"

# Verify token access
shopware project:list
```

**Token Types and Use Cases:**

| Token Type | Purpose | Scope | Rotation Frequency |
|------------|---------|-------|-------------------|
| **Personal Access Token** | Development and testing | Full account access | 90 days |
| **CI/CD Token** | Automated deployments | Project-specific | 180 days |
| **Service Account Token** | Service-to-service communication | Limited scope | 365 days |
| **Emergency Token** | Break-glass scenarios | Full access | 30 days |

#### Multi-Environment Token Strategy

Implement separate tokens for different environments to minimize blast radius:

```bash
# .env.local (never commit this file)
PLATFORM_PROJECT_ID=your-project-id
PLATFORM_API_TOKEN=your-api-token
DATABASE_URL=mysql://user:pass@host:port/dbname
REDIS_URL=redis://host:port
```

#### Security Implementation Checklist

✅ **Token Management:**

- Use separate tokens per environment (dev, staging, production).
- Implement automatic token rotation policies (rotate every 90 days).
- Limit token permissions to minimum required scope.
- Store tokens in secure credential managers (1Password, AWS Secrets Manager, HashiCorp Vault).

✅ **Access Control:**

- Implement least-privilege access principles.
- Use role-based access control (RBAC).
- Regularly audit access permissions.
- Enable multi-factor authentication (MFA) where possible.

✅ **Secret Management:**

- Never commit secrets to version control.
- Use platform-specific secret management services.
- Encrypt secrets at rest and in transit.
- Implement secret rotation procedures.

✅ **Monitoring and Alerting:**

- Monitor for suspicious access patterns.
- Set up alerts for failed authentication attempts.
- Log all credential usage for audit purposes.
- Implement automated security scanning.

#### Platform-Specific Secret Management

**Shopware PaaS:**

```bash
# Configure environment variables
shopware project:variable:set --environment=production DATABASE_URL="mysql://user:pass@host/db"

# Set application secrets
shopware project:variable:set --environment=production APP_SECRET="your-app-secret"
```

### Team Access Management

For collaborative projects, establish clear access patterns and role definitions:

#### Access Control Configuration

```yaml
# .platform/access.yaml
users:
  - email: "developer@company.com"
    role: "contributor"
  - email: "devops@company.com"
    role: "admin"
  - email: "manager@company.com"
    role: "viewer"
```

## Repository Setup Options

There are two options to set up the repository. Have a look at the differences and see what fits the best to your project:

### Option 1: Shopware Template Repository

The fastest way to start is using the official Shopware production template:

```bash
# Clone the Shopware production template
git clone https://github.com/shopware/production.git my-shopware-project
cd my-shopware-project

# Install PaaS configurations (CRITICAL STEP)
# When prompted, generally choose "shopware/paas-meta"
composer require paas

# Remove the original git history
rm -rf .git
git init
git add .
git commit -m "Initial commit from Shopware template"

# Configure the PaaS CLI with your project id
shopware project:set-remote PROJECT_ID

# Add your remote repository
git remote add origin https://github.com/your-org/your-project.git
git push -u origin main
```

<Callout title="Note" type="info">

You can find your PaaS project ID by running the following command in your project's root directory:

```bash
shopware project:list
```

</Callout>

#### Shopware Template Benefits

Using the template provides several advantages:

- Pre-configured Shopware installation.
- Essential services (Redis, Elasticsearch) are already set up.
- Deployment hooks and scripts are included.
- Security best practices are implemented.
- Standardized project structure.
- CI/CD pipeline configuration.

#### Shopware Template Considerations

Before using the template, consider:

- May include unnecessary dependencies.
- Could have unused configurations.
- Might need cleanup for your specific needs.
- Could require additional customization.

### Option 2: Custom Scaffolding

For more control, create a custom project structure:

```bash
# Create project directory
mkdir my-shopware-project
cd my-shopware-project

# Initialize composer project
composer create-project shopware/core:^6.5 . --no-install

# Add PaaS-specific configurations
mkdir -p .platform
mkdir -p config/packages/prod
mkdir -p config/packages/dev
```

#### Custom Scaffolding Benefits

✅ Minimal, clean starting point
✅ Easier to understand and modify
✅ No unnecessary components
✅ Full control over dependencies

#### Custom Scaffolding Considerations

If you choose to scaffold from scratch:

- More setup work is required.
- You need to implement all configurations.
- You must set up all dependencies.
- Requires more testing.
- Greater flexibility for customization.

```bash
# Example of custom scaffolding
mkdir my-shopware-project
cd my-shopware-project
composer create-project shopware/platform .
```

## Directory & Configuration Structure

### Recommended Project Structure

```bash
my-shopware-project/
├── .platform/                 # PaaS platform configuration
│   ├── applications.yaml      # Application definitions
│   ├── routes.yaml            # Routing configuration
│   └── services.yaml          # Service definitions
├── config/
│   ├── packages/
│   │   ├── dev/               # Development-specific config
│   │   ├── prod/              # Production-specific config
│   │   └── test/              # Test environment config
│   ├── bundles.php
│   └── services.yaml
├── src/                       # Custom application code
├── templates/                 # Twig templates
├── public/                    # Web-accessible files
├── var/                       # Cache, logs, sessions
├── vendor/                    # Composer dependencies
├── .env                       # Environment template
├── .env.local.example         # Local environment example
├── .gitignore
├── composer.json
└── README.md
```

### Essential Configuration Files

#### .platform/applications.yaml

```yaml
app:
    type: 'php:8.2'
    size: 'S'
    
    dependencies:
        php:
            composer/composer: '^2'
    
    web:
        locations:
            '/':
                root: 'public'
                passthru: '/index.php'
                index:
                    - 'index.php'
                expires: '1d'
                scripts: true
                allow: false
                rules:
                    '\.(css|js|gif|jpe?g|png|svg|ico|woff2?|ttf|eot)$':
                        allow: true
                        expires: '1w'
    
    disk: 2048
    
    mounts:
        '/var': { source: 'local', source_path: 'var' }
        '/public/media': { source: 'local', source_path: 'media' }
        '/public/thumbnail': { source: 'local', source_path: 'thumbnail' }
        '/public/sitemap': { source: 'local', source_path: 'sitemap' }
        '/files': { source: 'local', source_path: 'files' }
    
    hooks:
        build: |
            set -e
            composer install --no-dev --optimize-autoloader
            bin/console assets:install
        deploy: |
            set -e
            bin/console cache:clear
            bin/console database:migrate --all
```

#### .platform/services.yaml

```yaml
database:
    type: 'mariadb:10.6'
    disk: 2048

redis:
    type: 'redis:7.0'

elasticsearch:
    type: 'elasticsearch:7.17'
    disk: 1024
```

#### .platform/routes.yaml

```yaml
"https://{default}/":
    type: upstream
    upstream: "app:http"
    cache:
        enabled: true
        default_ttl: 0
        cookies: ['session', 'private-content-version']
        vary: ['Accept-Encoding', 'X-Requested-With']

"https://www.{default}/":
    type: redirect
    to: "https://{default}/"
```

### Environment-Specific Configuration

#### config/packages/prod/shopware.yaml

```yaml
shopware:
    filesystem:
        private:
            type: "local"
            config:
                root: "%kernel.project_dir%/files"
        public:
            type: "local"
            config:
                root: "%kernel.project_dir%/public"
        temp:
            type: "local"
            config:
                root: "%kernel.project_dir%/var"
        theme:
            type: "local"
            config:
                root: "%kernel.project_dir%/public"
        asset:
            type: "local"
            config:
                root: "%kernel.project_dir%/public"
        sitemap:
            type: "local"
            config:
                root: "%kernel.project_dir%/public/sitemap"
```

## Security Considerations

### .gitignore Configuration

A properly configured `.gitignore` file is essential for maintaining security and preventing sensitive information from being committed to your repository. This file tells Git which files and directories to exclude from version control.

```txt
# Environment files
.env.local
.env.local.php
.env.*.local

# Platform-specific
.platform/local/

# Shopware
/install.lock
/public/recovery/
/public/sitemap/
/public/thumbnail/
/var/
/vendor/
/files/

# IDE
.idea/
.vscode/
*.swp
*.swo

# Operating System Files
.DS_Store
Thumbs.db
```

**Key Security Considerations:**

- **Environment Files**: Never commit `.env` files containing sensitive data like API keys, database credentials, or application secrets.
- **Platform Configuration**: Keep local platform configurations separate from version-controlled templates.
- **Application Data**: Exclude user-generated content, media files, and application state files.
- **Development Artifacts**: Remove IDE configurations, temporary files, and build artifacts.

### Credential Management Checklist

1. API tokens stored are in environment variables.
2. Separate credentials per environment.
3. Regular token rotation schedule is set.
4. Team access is properly configured.
5. Sensitive files are in .gitignore.
6. Credential backup strategy is in place.

## Troubleshooting Common Issues

When working with PaaS platforms and repository management, you may encounter various issues. This section provides solutions for the most common problems and their diagnostic approaches.

### Authentication & Access Issues

#### Token Authentication Failures

**Symptoms:** 401 Unauthorized errors, "Invalid token" messages, or authentication timeouts.

**Diagnostic Steps:**

```bash
# Verify token format and validity
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.platform.sh/user

# Check token permissions and scope
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.platform.sh/projects
```

**Common Solutions:**

- **Token Expired**: Generate a new token and update your configuration.
- **Insufficient Permissions**: Request additional scopes from your administrator.
- **Token Revoked**: Contact your platform administrator to verify token status.
- **Network Issues**: Check firewall settings and proxy configurations.

#### Repository Access Issues

**Symptoms:** Git push/pull failures, SSH connection timeouts, or permission denied errors.

**Diagnostic Steps:**

```bash
# Verify SSH connection to platform
ssh -T git@git.platform.sh

# Check repository URL configuration
git remote -v

# Test repository access permissions
git ls-remote --heads origin
```

**Common Solutions:**

- **SSH Key Issues**: Ensure your SSH key is added to your platform account.
- **Repository URL**: Verify the correct repository URL is configured.
- **Permission Denied**: Check if you have access to the specific repository.
- **Network Connectivity**: Test connectivity to the platform's Git server.

#### Permission Errors

**Symptoms:** "Access denied" messages, inability to create environments, or restricted operations.

**Diagnostic Steps:**

```bash
# Verify current user identity
shopware whoami

# Check project access permissions
shopware project:list

# Test environment access
shopware project:environment:list
```

## Next Steps

In the next learning unit, we'll explore how to design effective environment strategies and provision the essential services your Shopware application needs to run successfully on PaaS.