Services

Services are the main building blocks of the Ptah.sh system.

Note

It’s important to distinguish between Docker Swarm’s “Services” and Ptah.sh’s “Services”. While Docker Swarm Services are part of the native Docker orchestration system and define tasks to execute on nodes, Ptah.sh Services are higher-level abstractions that can include multiple processes, configurations, and resources. A single Ptah.sh Service may create and manage multiple Docker Swarm services behind the scenes.

Processes

In Ptah.sh, services are composed of one or more “processes”. Each process represents a Docker Swarm Service and defines its own configuration and behavior.

For example, a PostgreSQL service in Ptah.sh may be defined as two processes: the PostgreSQL server itself and pgpool running as a sidecar container. Each of these processes would correspond to a separate Docker Swarm Service.

Workers

Workers represent individual Docker Swarm Services within a Ptah.sh Service. Each worker can be configured independently with its own settings, allowing for flexible and granular control over your application’s components.

Each worker can have the following configurations:

1. Docker Image: Specify the Docker image to use for this worker.
2. Registry: Choose between public registries or pre-configured private registries.
3. Git Repository: Specify the Git repository to use for this worker.
4. Replicas: Define how many instances of this worker should run.
5. Launch Mode: Specify how and when this worker should be started (e.g., always, on-demand, or scheduled).
6. Healthcheck: Configure health monitoring for the worker.
7. Release Command: Set up commands to run before the main process starts.
8. Command (Entrypoint): Define the main command to run for this worker.

Note

Workers within a Process share certain resources and configurations. These shared elements include config files, volumes, secret files, environment variables, and secret variables. This allows for consistent configuration across all workers in a service while still allowing for individual worker customization.

This worker-based approach allows you to create complex, multi-component services where each component (worker) can be fine-tuned to your specific needs while maintaining a shared configuration base.

Learn more about workers in the Daemons and Workers page.

Volumes

Volumes are shared among all workers within a service. Each service may have a list of volumes that are mounted to its workers’ containers. These volumes are Docker Swarm volumes, which provide persistent storage for your services.

Docker Swarm volumes offer several benefits:

• Data persistence across container restarts
• Easy sharing of data between containers
• Improved performance compared to bind mounts

Volumes can be configured with different drivers, including local storage or network-attached storage solutions. Additionally, Ptah.sh supports backing up these volumes to S3-compatible storage, ensuring data durability and facilitating disaster recovery.

For more information on S3 storage integration, see the S3 Storages page.

Environment Variables

Environment variables are shared among all workers within a service. Each service may have a list of environment variables that are set on its workers’ containers.

Environment variables are key-value pairs that are part of the worker’s runtime environment. They are used to configure applications and pass information into containers at runtime. This approach aligns with the Twelve-Factor App methodology, which recommends storing configuration in the environment.

Common uses for environment variables include:

• Setting database connection strings
• Configuring API keys and secrets
• Specifying runtime modes (e.g., development, production)
• Adjusting application behavior without changing code

By using environment variables, you can easily manage different configurations across various deployment environments and keep sensitive information out of your codebase.

Secret Variables

Secret variables are shared among all workers within a service. In addition to regular environment variables, Ptah.sh supports secret variables. These are similar to environment variables but offer enhanced security features:

1. Storage: Secret variables are stored solely on the Docker Swarm cluster.
2. Encryption: The data is encrypted with a Docker Swarm cluster’s key while it is stored in the task execution queue.
3. Access: Secrets are only decrypted and made available to the container at runtime.

Secret variables are ideal for storing sensitive information such as:

• API keys
• Database passwords
• OAuth tokens
• SSL certificates

To use secret variables in Ptah.sh:

1. When configuring your service, locate the “Secret Variables” section in the worker settings.
2. Add your secret key-value pairs.
3. Reference these secrets in your application code as you would with regular environment variables.

By utilizing secret variables, you can ensure that sensitive data is kept secure and separate from your regular configuration, reducing the risk of accidental exposure or unauthorized access.

Config Files

Config files are shared among all workers within a service. Each service may have a list of config files that are mounted to its workers’ containers. Users can specify:

1. Path: The location where the file should be mounted in the container
2. File Contents: The actual content of the configuration file

This allows for easy management and deployment of configuration files alongside your services.

Examples

1. Nginx configuration:

   • Path: /etc/nginx/nginx.conf
   • File Contents:

     user nginx;
     worker_processes auto;
     error_log /var/log/nginx/error.log;
     pid /run/nginx.pid;
     
     events {
         worker_connections 1024;
     }
     
     http {
         server {
             listen 80;
             server_name example.com;
             location / {
                 proxy_pass http://backend:8080;
             }
         }
     }

2. PHP configuration:

   • Path: /usr/local/etc/php/php.ini
   • File Contents:

     memory_limit = 256M
     upload_max_filesize = 20M
     post_max_size = 20M
     max_execution_time = 120

3. Application-specific configuration:

   • Path: /app/config.json
   • File Contents:

     {
       "database": {
         "host": "db.example.com",
         "port": 5432,
         "name": "myapp"
       },
       "cache": {
         "driver": "redis",
         "host": "redis.example.com"
       },
       "logging": {
         "level": "info",
         "file": "/var/log/myapp.log"
       }
     }

These examples demonstrate how you can use config files to manage various types of configurations, from web server settings to application-specific options, directly within your Ptah.sh service definition.

Secret Files

Secret files are shared among all workers within a service. In addition to config files, Ptah.sh supports secret files. These are similar to config files but offer enhanced security features:

1. Storage: Secret files are stored solely on the Docker Swarm cluster.
2. Encryption: The file contents are encrypted with a Docker Swarm cluster’s key while stored in the task execution queue.
3. Access: Secrets are only decrypted and made available to the container at runtime.
4. Confidentiality: The contents of secret files cannot be read by the Ptah.sh panel.

Secret files are ideal for storing sensitive information that needs to be mounted as a file in the container, such as:

• SSL certificates and private keys
• OAuth client secrets
• API configuration files with sensitive data
• Database connection files

To use secret files in Ptah.sh:

1. When configuring your service, locate the “Secret Files” section in the worker settings.
2. Specify the path where the file should be mounted in the container.
3. Provide the contents of the secret file.

Examples

1. SSL Certificate:

   • Path: /etc/ssl/private/example.com.pem
   • File Contents: (The actual SSL certificate and private key)

2. Database Connection File:

   • Path: /app/db-credentials.json
   • File Contents:

     {
       "host": "db.internal",
       "port": 5432,
       "username": "app_user",
       "password": "super_secret_password",
       "database": "myapp_production"
     }

3. OAuth Client Secret:

   • Path: /app/oauth_secret.txt
   • File Contents: (The actual OAuth client secret)

4. API Configuration:

   • Path: /app/api_config.yml
   • File Contents:

     api_key: "your_very_secret_api_key"
     endpoint: "https://api.example.com/v2"
     rate_limit: 1000

By utilizing secret files, you can securely manage sensitive data that needs to be mounted as files in your containers, ensuring that this information remains encrypted and inaccessible to the Ptah.sh panel or unauthorized users.

Expose as HTTP(s)

Each worker can be configured for public access over the internet using either direct port publishing or Caddy endpoints.

You can use Caddy endpoints to map services to HTTP and HTTPS. When configuring a Caddy endpoint, you need to provide the following information:

1. Container Protocol: Currently, either HTTP or FCGI
2. Container Port: The port your service is listening on inside the container
3. Published Port: Either HTTP (80) or HTTPS (443)
4. Domain: The domain name for the service
5. Path: The URL path to listen on, which can include placeholders (e.g., /* listens at any request path starting from the root)

This configuration allows for flexible and powerful routing of HTTP/HTTPS traffic to your services, including support for multiple domains and path-based routing.

Redirect Rules

Redirect Rules allow users to specify URL redirects. When configuring a redirect, you need to provide:

1. Domain From: The source domain
2. Domain To: The destination domain
3. Status: The HTTP redirect status code (301, 302, 307, or 308)
4. Path From: The source path (supports regular expressions)
5. Path To: The destination path

Redirects are useful for scenarios such as domain changes, HTTP to HTTPS redirects, or URL structure changes.

Examples

1. Blog migration:

   • Domain From: old-domain.com
   • Domain To: new-domain.com
   • Status: 301
   • Path From: /blog/(.*)
   • Path To: /articles/$1

   This would permanently redirect all blog posts from the old domain to the articles section on the new domain.

2. www to non-www redirect:

   • Domain From: www.example.com
   • Domain To: example.com
   • Status: 301
   • Path From: /(.*)
   • Path To: /$1

   This would permanently redirect all requests from the www subdomain to the root domain, maintaining the same path and query parameters.

These examples demonstrate how Redirect Rules can be used to manage common URL redirection scenarios in Ptah.sh.

Rewrite Rules

Rewrite Rules allow users to modify URLs internally without changing what the user sees in their browser. When configuring a rewrite, you need to provide:

1. Path From: The source path (supports regular expressions)
2. Path To: The destination path

Rewrites are useful for implementing clean URLs, content organization, or URL structures that don’t directly map to your file system.

Examples

1. Clean URLs:

   • Path From: /products/(.*)/(.*)
   • Path To: /products.php?category=$1&item=$2

   This would internally rewrite a URL like /products/electronics/smartphone to /products.php?category=electronics&item=smartphone, allowing for a cleaner URL structure.

   These powerful routing features in Ptah.sh enable you to create sophisticated URL handling schemes without modifying your application code, improving both SEO and user experience.

Expose as TCP/UDP

When publishing ports directly, users can specify two port numbers:

1. The published port on the node (available from the internet)
2. The target port on the container

This allows for flexible port mapping between the host and the container, enabling you to expose services on specific ports while potentially using different internal port numbers.

Note

Use this method when you need to expose a service that is not HTTP/HTTPS. Ports are exposed as is, without any additional routing.

1-Click Apps

1-Click Apps are preconfigured applications that can be quickly deployed to your server node. They provide a streamlined way to set up common services or processes without the need for manual configuration.

To use a 1-Click App when creating a service:

1. Navigate to the service creation page.
2. Select the desired 1-Click App from the available templates.
3. Click “Use template” to apply the 1-Click App configuration to your new service.

We recommend using 1-Click Apps to deploy any service that is not part of your core system, as they come preconfigured with best practices and can save significant setup time.

For more detailed information on 1-Click Apps, including how to use them and their benefits, see the 1-Click Apps page.

You can browse all available 1-Click Apps in the Marketplace page.