Merge pull request #352 from PierreBeucher/minor-tweaks

Minor tweaks

Author: PierreBeucher

containers/sunshine/Dockerfile

@@ -5,28 +5,29 @@ WORKDIR /app
 # Sunshine
 # https://github.com/LizardByte/Sunshine/releases
 FROM download-base AS download-sunshine
-ARG SUNSHINE_VERSION=2026.218.44016
-RUN curl -L -o /app/sunshine.deb "https://github.com/LizardByte/Sunshine/releases/download/v${SUNSHINE_VERSION}/sunshine-ubuntu-24.04-amd64.deb"
+ARG SUNSHINE_VERSION=2025.924.154138
+RUN curl -fL -o /app/sunshine.deb "https://github.com/LizardByte/Sunshine/releases/download/v${SUNSHINE_VERSION}/sunshine-ubuntu-24.04-amd64.deb"
 
 # Steam
 # https://repo.steampowered.com/steam/archive/stable/
 FROM download-base AS download-steam
 ARG STEAM_VERSION="1.0.0.81"
-RUN curl -o /app/steam-libs-amd64.deb "https://repo.steampowered.com/steam/archive/stable/steam-libs-amd64_${STEAM_VERSION}_amd64.deb"
-RUN curl -o /app/steam-libs-i386.deb "https://repo.steampowered.com/steam/archive/stable/steam-libs-i386_${STEAM_VERSION}_i386.deb"
-RUN curl -o /app/steam.deb "https://repo.steampowered.com/steam/archive/stable/steam-launcher_${STEAM_VERSION}_all.deb"
+RUN curl -f -o /app/steam-libs-amd64.deb "https://repo.steampowered.com/steam/archive/stable/steam-libs-amd64_${STEAM_VERSION}_amd64.deb"
+RUN curl -f -o /app/steam-libs-i386.deb "https://repo.steampowered.com/steam/archive/stable/steam-libs-i386_${STEAM_VERSION}_i386.deb"
+RUN curl -f -o /app/steam.deb "https://repo.steampowered.com/steam/archive/stable/steam-launcher_${STEAM_VERSION}_all.deb"
 
 # Lutris
 # https://github.com/lutris/lutris/releases
 FROM download-base AS download-lutris
 ARG LUTRIS_VERSION="0.5.20"
-RUN curl -L -o /app/lutris.deb "https://github.com/lutris/lutris/releases/download/v${LUTRIS_VERSION}/lutris_${LUTRIS_VERSION}_all.deb"
+RUN curl -fL -o /app/lutris.deb "https://github.com/lutris/lutris/releases/download/v${LUTRIS_VERSION}/lutris_${LUTRIS_VERSION}_all.deb"
 
 # Heroic
 # https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases
 FROM download-base AS download-heroic
 ARG HEROIC_VERSION="2.19.1"
-RUN curl -L -o /app/heroic.deb "https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/download/v${HEROIC_VERSION}/Heroic-${HEROIC_VERSION}-linux-amd64.deb"
+
+RUN curl -fL -o /app/heroic.deb "https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases/download/v${HEROIC_VERSION}/Heroic-${HEROIC_VERSION}-linux-amd64.deb"
 
 # 
 # Sunshine image based on Ubuntu 24.04
@@ -178,7 +179,6 @@ RUN locale-gen en_US.UTF-8 && \
 RUN --mount=type=cache,target=/var/cache --mount=type=tmpfs,target=/var/log --mount=type=bind,from=download-sunshine,source=/app,target=/app <<_SUNSHINE
 
 set -e
-
 apt update
 apt install -y /app/sunshine.deb
 

containers/sunshine/overlay/cloudy/conf/xfce4-default/panel/launcher-12/lutris.desktop

@@ -1,5 +1,5 @@
 [Desktop Entry]
-Name=Leroic
+Name=Lutris
 Comment=Managing and play games on Lutris
 Exec=lutris-start.sh
 Icon=lutris

docs/src/contributing/contribution-guide.md

@@ -37,6 +37,11 @@ Here's a typical workflow outline for contributions:
   - [Ansible playbook](#ansible-playbook)
   - [Local Pulumi stack manipulation](#local-pulumi-stack-manipulation)
   - [Local Virtual Machine as Cloudy Pad instance](#local-virtual-machine-as-cloudy-pad-instance)
+  - [Connect to Cloudy Pad VM and container](#connect-to-cloudy-pad-vm-and-container)
+  - [Debug Proton / Wine and game run](#debug-proton--wine-and-game-run)
+  - [Debug process CPU usage or affinity](#debug-process-cpu-usage-or-affinity)
+  - [Debug process environment variable](#debug-process-environment-variable)
+  - [Enable debug log with Steam and Proton](#enable-debug-log-with-steam-and-proton)
 - [Create a Pull Request with your changes](#create-a-pull-request-with-your-changes)
   - [Review process](#review-process)
 - [Useful commands](#useful-commands)
@@ -349,6 +354,78 @@ vagrant ssh
 $ docker compose -f /vagrant/test/resources/docker-compose.vagrant.yml -p sunshine up -d --force-recreate
 ```
 
+### Connect to Cloudy Pad VM and container
+
+To connect via SSH on instance, see: [Connect via SSH](../usage/ssh.md)
+
+### Debug Proton / Wine and game run
+
+To run directly Proton or Wine and see how it behaves, first run the game in a standard way and re-use the same command to reproduce issue or situation. 
+
+Identify process running game, then get their env variables:
+
+```sh
+ps -ef 
+
+GAME_PID=1234 cat proc/$GAME_PID$/environ | tr '\0' '\n'
+```
+
+Steam specifics: variables we want to re-use:
+
+```sh
+export STEAM_COMPAT_CLIENT_INSTALL_PATH="/cloudy/data/Steam"
+export STEAM_COMPAT_DATA_PATH="/cloudy/data/Steam/steamapps/compatdata/1903340"
+```
+
+Then run game manually (re-use actual command), eg.:
+
+```sh
+python3 "/cloudy/data/Steam/steamapps/common/Proton 10.0/proton" waitforexitandrun "C:\\windows\\system32\\cmd.exe" /c "path/to/game.exe"
+```
+
+Example for Steam with Expedition 33:
+
+```sh
+python3 /cloudy/data/Steam/steamapps/common/Proton 10.0/proton waitforexitandrun /cloudy/data/Steam/steamapps/common/Expedition 33/Expedition33_Steam.exe
+```
+
+### Debug process CPU usage or affinity
+
+Specific instructions to debug CPU usage, especially linked to CPU affinity. (eg. for [#335](https://github.com/PierreBeucher/cloudypad/issues/335))
+
+```sh
+# Show all process
+ps -ef
+
+# Show process using NVIDIA GPU
+nvidia-smi
+
+# Show process CPU affinity
+taskset -pc PID
+```
+
+### Debug process environment variable
+
+```sh
+cat /proc/5096/environ | tr '\0' '\n'
+```
+
+### Enable debug log with Steam and Proton
+
+Connect on instance and `docker exec -it -u cloudy cloudy bash` to run a shell in container as cloudy user, then run Steam directly:
+
+```sh
+STEAM_LINUX_RUNTIME_LOG=1 STEAM_LINUX_RUNTIME_VERBOSE=1 PRESSURE_VESSEL_VERBOSE=1 PROTON_LOG=1 PROTON_LOG_DIR=/tmp steam
+```
+
+Possibly also add (as per [Steam debug logging instructions](https://github.com/ValveSoftware/steam-runtime/blob/master/doc/reporting-steamlinuxruntime-bugs.md) ):
+
+```sh
+CAPSULE_DEBUG=all
+G_MESSAGES_DEBUG=all
+```
+
+
 ## Create a Pull Request with your changes
 
 When your changes are ready, you can [create a Pull Request](https://github.com/PierreBeucher/cloudypad/pulls). Please make sure to:

docs/src/contributing/maintenance.md

@@ -73,6 +73,8 @@ Then:
   - [ ] Base image version `FROM` - See available tags from [Docker Hub](https://hub.docker.com/_/ubuntu). Make sure to use the imaghe SHA for reproducibility.
   - [ ] Steam version `CLOUDYPAD_STEAM_VERSION` - see stable version at [Steam archive](https://repo.steampowered.com/steam/archive/stable)
   - [ ] Update `SUNSHINE_VERSION` with [latest Sunshine release](https://github.com/LizardByte/Sunshine/releases)
+    - Prefer the Latest release
+    - Do NOT use Release Candidate or Pre-release, make sure to use actual release. Pre-release and RC may be removed from GitHub later, we need a release that will be kept available to ensure reproducibility of our build.
   - [ ] Update `LUTRIS_VERSION` with [latest Lutris release](https://github.com/lutris/lutris/releases)
   - [ ] Update `HEROIC_VERSION` with [latest Heroic Games Launcher version](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/releases)
   - [ ] Update `CLOUDYPAD_HEROIC_DEFAULT_GEPROTON_VERSION` with [latest GE-Proton version](https://github.com/GloriousEggroll/proton-ge-custom/releases)

src/cli/command.ts

@@ -125,6 +125,8 @@ export const CLI_OPTION_AUTO_STOP_TIMEOUT = new Option('--autostop-timeout <seco
 
 export const CLI_OPTION_ANSIBLE_ADDITIONAL_ARGS = new Option('--ansible-additional-args <args>', 'Additional Ansible arguments to pass to configuration, eg. "--tags data-disk -vvv"')
 
+export const CLI_OPTION_ANSIBLE_ARGS_OVERRIDE = new Option('--ansible-args-override <args>', 'Override Ansible arguments to pass to configuration, eg. "--tags data-disk -vvv"')
+
 export const CLI_OPTION_RETRIES = new Option('--retries <number>', 'Number of retries when deploying, configuring, starting, stopping or destroying instance')
     .argParser(parseInt)
 export const CLI_OPTION_RETRY_DELAY = new Option('--retry-delay <seconds>', 'Retry delay in seconds when deploying, configuring, starting, stopping or destroying instance')

src/cli/program.ts

@@ -17,7 +17,7 @@ import { CloudypadClient } from '../core/client';
 import { CoreConfig } from '../core/config/interface';
 import { InstanceManagerBuilder } from '../core/manager-builder';
 import { InstanceManager } from '../core/manager';
-import { CLI_OPTION_RETRIES, CLI_OPTION_RETRY_DELAY, CLI_OPTION_FORCE_PULUMI_CANCEL } from './command';
+import { CLI_OPTION_RETRIES, CLI_OPTION_RETRY_DELAY, CLI_OPTION_FORCE_PULUMI_CANCEL, CLI_OPTION_ANSIBLE_ADDITIONAL_ARGS, CLI_OPTION_ANSIBLE_ARGS_OVERRIDE } from './command';
 
 const logger = getLogger("program")
 
@@ -184,7 +184,8 @@ export function buildProgram(){
                 analyticsClient.sendEvent(RUN_COMMAND_STOP)
 
                 console.info(`Stopping instance ${name}...`)
-                console.info(`ℹ️ Stopping may take some time to complete while your instance's data is put to sleep for better cost efficiency (data disk snapshot may be long).`)
+                // need 2 spaces otherwise might not show properly  
+                console.info(`ℹ️  Stopping may take some time to complete while your instance's data is put to sleep for better cost efficiency (data disk snapshot may be long).`)
 
                 const m = await getInstanceManager(name)
                 await m.stop({ 
@@ -293,6 +294,7 @@ export function buildProgram(){
         .addOption(CLI_OPTION_RETRIES)
         .addOption(CLI_OPTION_RETRY_DELAY)
         .addOption(CLI_OPTION_FORCE_PULUMI_CANCEL)
+        .addOption(CLI_OPTION_ANSIBLE_ARGS_OVERRIDE)
         .action(async (name, opts) => {
             try {
                 analyticsClient.sendEvent(RUN_COMMAND_CONFIGURE)
@@ -301,7 +303,8 @@ export function buildProgram(){
                 await m.configure({ 
                     retries: opts.retries, 
                     retryDelaySeconds: opts.retryDelay,
-                    pulumiCancel: opts.forcePulumiCancel
+                    pulumiCancel: opts.forcePulumiCancel,
+                    ansibleArgsOverride: opts.ansibleArgsOverride ? [opts.ansibleArgsOverride] : undefined
                 })
 
                 console.info("")
@@ -318,6 +321,7 @@ export function buildProgram(){
         .addOption(CLI_OPTION_RETRIES)
         .addOption(CLI_OPTION_RETRY_DELAY)
         .addOption(CLI_OPTION_FORCE_PULUMI_CANCEL)
+        .addOption(CLI_OPTION_ANSIBLE_ARGS_OVERRIDE)
         .action(async (name, opts) => {
 
             const manager = await getInstanceManager(name)
@@ -334,7 +338,8 @@ export function buildProgram(){
             await manager.deploy({ 
                 retries: opts.retries, 
                 retryDelaySeconds: opts.retryDelay,
-                pulumiCancel: opts.forcePulumiCancel
+                pulumiCancel: opts.forcePulumiCancel,
+                ansibleArgsOverride: opts.ansibleArgsOverride ? [opts.ansibleArgsOverride] : undefined
             })
         })
 

src/core/manager.ts

@@ -35,9 +35,17 @@ export interface ActionOptions {
 }
 
 export interface DeployOptions extends ActionOptions {
+    /**
+     * Override Ansible arguments to pass to configuration, e.g. ["--tags", "nvidia-container-toolkit"]
+     */
+    ansibleArgsOverride?: string[]
 }
 
 export interface ConfigureOptions extends ActionOptions {
+    /**
+     * Override Ansible arguments to pass to configuration, e.g. ["--tags", "nvidia-container-toolkit"]
+     */
+    ansibleArgsOverride?: string[]
 }
 
 export interface ProvisionOptions extends ActionOptions {
@@ -266,9 +274,15 @@ export class GenericInstanceManager<ST extends InstanceStateV1> implements Insta
 
         this.logger.debug(`Configuring instance ${this.name()}`)
 
-        const currentState = await this.getState()
-        const configurationAnsibleAdditionalArgs = currentState.configuration.input.ansible?.additionalArgs ? 
-            [currentState.configuration.input.ansible.additionalArgs] : undefined
+        // Prefer CLI-provided args override over state-stored args
+        let configurationAnsibleAdditionalArgs: string[] | undefined
+        if (opts?.ansibleArgsOverride) {
+            configurationAnsibleAdditionalArgs = opts.ansibleArgsOverride
+        } else {
+            const currentState = await this.getState()
+            configurationAnsibleAdditionalArgs = currentState.configuration.input.ansible?.additionalArgs ? 
+                [currentState.configuration.input.ansible.additionalArgs] : undefined
+        }
 
         await this.addEvent(InstanceEventEnum.ConfigurationBegin)
 
@@ -352,6 +366,16 @@ export class GenericInstanceManager<ST extends InstanceStateV1> implements Insta
 
                 await this.doProvision(opts)
 
+                // Check if server is actually running after provision
+                // Provisioning may not have started the server if it was existing but not running
+                // eg. if instance server was stopped by auto-stop feature rather than stop() operation
+                const runner = await this.buildRunner()
+                const serverStatus = await runner.serverStatus()
+                if(serverStatus !== ServerRunningStatus.Running){
+                    this.logger.debug(`Server is not running after provision (status: ${serverStatus}), starting it now`)
+                    await runner.start({ wait: true })
+                }
+            
                 // always reconfigured instance using limited Ansible run to avoid re-running full configuration on every start
                 await this.doConfigure(['-t', 'ratelimit,data-disk,sunshine'])
             }