Advanced

Iris is a javascript application built with React and Redux. Iris is open-source software and you are welcome to experiment with it, however you must credit the author (James Barnsley, @jaedb) and never charge for it's use.

Commands

Iris lets you build a library of commands so you can send arbitrary HTTP requests to other services (local and remote). This is handy for integrating with IR blasters, networked amplifiers and IoT services like IFTTT. These commands are available as buttons in the main play toolbar (under the Outputs icon).

To manage these commands see Settings > Commands. Please note that these commands are stored on the Mopidy server in a plain text file, so all users of your Mopidy server will be able to view, edit and run them.

Development

To develop Iris, you need to run it from a local directory that you can manage. You will also need to recompile the code once you've made your changes.

1. Remove previous installations of Iris (eg pip uninstall Mopidy-Iris)
2. Clone this repository git clone git@github.com:jaedb/Iris.git ./ to your local system
3. Install Node.js and NPM
4. Install all dependencies npm install
5. Compile Iris npm run build:dev (and npm run build:prod for final minified code). You can watch for file changes by running npm run watch:dev instead to auto-build (you then just need to refresh the browser to load recompiled code).
6. Install Iris in develop mode python ./setup.py develop
7. Run Mopidy mopidy

Test mode

The production build of Iris omits any useful console logging for obvious reasons. To help with debugging and development you can load non-minified code by using Iris in Test Mode. Enable Test Mode under Settings > Debug > Test mode.

Please note that you will need to refresh the window after enabling or disabling Test Mode for the changes to take effect.

Debugging

You can trace issues using Iris' debug tools, found under Settings > Debugger. To use these to their full capacity, you need to be running Iris in test mode (as above).

You can access the full Redux store (the data store for Iris) by typing window._store.getState() into your browser's developer console (ie Firebug).

If you ever get stuck with a corrupt environment you can reset your localStorage. This is where all client-side configuration is stored. Clear this using your browser's developer tools (eg Firebug) by running localStorage.clear().

Encryption (HTTPS/WSS)

Mopidy (and thus it's extensions) does not natively support SSL (HTTPS and WSS). If you wish to run Mopidy over SSL, Mopidy developers recommend using a proxy to create a secure connection. I have included example setups for both Apache2 and nginx below.

Apache

You will need to enable the wstunnel module on Apache (sudo a2enmod proxy_wstunnel) to proxy websocket connections.

<VirtualHost *:80>
        # Leave empty (or "*") to listen to all domains
        ServerName iris.mylocaldomain

        # Redirect non-https requests to https
        RewriteRule ^(.*)$ http://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>

<VirtualHost *:443>
        # Leave empty (or "*") to listen to all domains
        ServerName iris.mylocaldomain

        # Optional: set this to wherever Iris is installed (depends on your setup)
        DocumentRoot /usr/local/lib/python2.7/dist-packages/mopidy_iris/static/
        <Directory /usr/local/lib/python2.7/dist-packages/mopidy_iris/static>
                RewriteEngine on

                # rewite all requests at /iris/ (but NOT ./ws) to accommodate the
                # ./mopidy/{extension} URL format
                RewriteCond %{REQUEST_URI} !^/ws/
                RewriteRule ^iris/(.*)$ /$1 [L]
        </Directory>

        RewriteEngine on
        ProxyRequests off
        ProxyPreserveHost on

        # Mopidy websocket
        ProxyPass /mopidy/ws/ ws://127.0.0.1:6680/mopidy/ws/
        ProxyPassReverse /mopidy/ws/ ws://127.0.0.1:6680/mopidy/ws/

        # Local-Images
        ProxyPass /images/ ws://127.0.0.1:6680/images/
        ProxyPassReverse /images/ ws://127.0.0.1:6680/images/

        # Iris websocket (Pusher)
        ProxyPass /iris/ws/ ws://127.0.0.1:6680/iris/ws/
        ProxyPassReverse /iris/ws/ ws://127.0.0.1:6680/iris/ws/

        # Iris HTTP endpoint
        ProxyPass /iris/http/ http://127.0.0.1:6680/iris/http/
        ProxyPassReverse /iris/http/ http://127.0.0.1:6680/iris/http/
</VirtualHost>

nginx

Thanks to @erikcvisser, @BrainStone, @Sieboldianus and @diabl0w for the following examples to get you started.

server {
        listen 80;

        # Set to "_" to listen to all domains
        server_name  MOPIDY_DOMAIN_NAME_HERE;

        return 301 https://$host$request_uri;
}

server {
        listen 443 ssl;

        # Set to "_" to listen to all domains
        server_name  MOPIDY_DOMAIN_NAME_HERE;

        # Update the following to reflect your certificate and key location
        ssl on;
        ssl_certificate PATH_TO_CERTICICATE_HERE;
        ssl_certificate_key PATH_TO_CERTICICATE_KEY_HERE;
        ssl_prefer_server_ciphers on;

        proxy_http_version 1.1;
        proxy_read_timeout 600s;
        location = / {
                return 301 /iris/;
        }

        location / {
                proxy_pass http://MOPIDY_SERVER_IP_HERE:6680;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $http_connection;
        }
}
server {
    listen 1780 ssl;

    server_name SNAPCAST_DOMAIN_NAME_HERE;

    location / {
        proxy_pass http://SNAPCAST_IP_HERE:1780;
        proxy_set_header X-Real-IP $remote_addr; 
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;

        # WebSocket support (nginx 1.4)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Preconfiguration

You can use query params in the URL to pre-populated Iris configuration values into the browser's local storage. This can be useful when sharing a link that you want to pre-configure certain parts of Iris.

Proceed at your own risk: This pre-seeds the Iris application state. You need to know what you're doing before you share preconfigured links.

If you manage to break your state configuration, you can reset this by running localState.clear() in your browser's developer tools.

Options

To start exploring possible configuration options, refer to the initialState section of src/store/index.js

You can also inspect Iris' current application state (in test mode) by opening your developer tools and entering window._store.getState()

Examples

• Skip the initial-setup screen: /iris/?ui={"initial_setup_complete":true}
• Set the username: /iris?pusher={"username": "MyUserNameHere"}
• Enable snapcast: /iris/?snapcast={"enabled":true,"host":"my-host.com","port":"443"}

This may also be used to enable Spotify, by passing ?spotify={...} with the valid token data. However, please be aware that this means you will be sharing a single login between sessions. Anybody with the pre-configured URL will be able to use the Spotify account in Iris. If the original user (who created the Spotify session) logs out, the token will continue to work for other users who access the page (the logout action does not invalidate the token for other users).