soundcloak/docs/INSTANCE_GUIDE.md

Setup

Docker

You need to have Docker and Git installed.

1. Clone this repository:

git clone https://git.maid.zone/stuff/soundcloak

2. Go into the cloned repository:

cd soundcloak

3. Make a copy of the example compose.yaml file:

cp compose.example.yaml compose.yaml

Make adjustments as needed.

4. Optional. Edit config:

Refer to Configuration guide for configuration information. Can be configured from environment variables or JSON file.

5. Run the container:

docker compose up -d

You might need to use sudo if you aren't running as root.

Use docker-compose instead of docker compose if that fails.

Soundcloak will now be up at 127.0.0.1:4664 (or the address you specified in your config). I recommend you run it through a reverse proxy (caddy, nginx, etc.)

Regular method

Refer to the developer guide

Extras

Not required but can help. If using docker, it already does this stuff for you.

• Precompressing static files

For more effective file serving: go tool soundcloakctl -nozstd precompress

You will have to run go tool soundcloakctl clean and re-run the above command each time static files change.

• Config codegen

Can help reduce binary size (if you don't use certain features) and performance (not by much): go tool soundcloakctl config codegen

You will have to re-run this each time you change config or config structure changes

Updating your instance

Docker

1. Retrieve the latest code:

git fetch origin
git pull

2. Rebuild and restart the container:

docker compose up --build -d

Use docker-compose instead of docker compose if that fails.

Regular method

Refer to the developer guide

Configuration/customization

Configuration guide

Click to view

You can only configure in one of the two ways:

• Using config file (soundcloak.json in current directory // your own path and filename)
• Using environment variables (SOUNDCLOAK_CONFIG must be set to FROM_ENV!)

Some notes:

• When specifying time, specify it in seconds.

JSON key	Environment variable	Default value	Description
None	SOUNDCLOAK_CONFIG	soundcloak.json	File to load soundcloak config from. If set to FROM_ENV, soundcloak loads the config from environment variables.
GetWebProfiles	GET_WEB_PROFILES	true	Retrieve links users set in their profile (social media, website, etc)
DefaultPreferences	DEFAULT_PREFERENCES	{"Player": "hls", "ProxyStreams": false, "FullyPreloadTrack": false, "ProxyImages": false, "ParseDescriptions": true, "AutoplayNextTrack": false, "DefaultAutoplayMode": "normal", "HLSAudio": "mpeg", "RestreamAudio": "mpeg", "DownloadAudio": "mpeg", "ShowAudio": false, "SearchSuggestions": false, "DynamicLoadComments": false}	see /_/preferences page. Read more
ProxyImages	PROXY_IMAGES	false	Enables proxying of images (user avatars, track covers etc)
ImageCacheControl	IMAGE_CACHE_CONTROL	max-age=600, public, immutable	Cache-Control header value for proxied images. Cached for 10 minutes by default.
ProxyStreams	PROXY_STREAMS	false	Enables proxying of song parts and hls playlist files
Restream	RESTREAM	false	Enables Restream Player in settings and the /_/restream/:author/:track endpoint. This player can be used without JavaScript. Restream also enables the button for downloading songs.
RestreamCacheControl	RESTREAM_CACHE_CONTROL	max-age=3600, public, immutable	Cache-Control header value for restreamed songs. Cached for 1 hour by default.
ClientIDTTL	CLIENT_ID_TTL	4 hours	Time until ClientID cache expires. ClientID is used for authenticating with SoundCloud API
UserTTL	USER_TTL	20 minutes	Time until User profile cache expires
UserCacheCleanDelay	USER_CACHE_CLEAN_DELAY	5 minutes	Time between each cleanup of the cache (to remove expired users)
TrackTTL	TRACK_TTL	20 minutes	Time until Track data cache expires
TrackCacheCleanDelay	TRACK_CACHE_CLEAN_DELAY	5 minutes	Time between each cleanup of the cache (to remove expired tracks)
PlaylistTTL	PLAYLIST_TTL	20 minutes	Time until Playlist data cache expires
PlaylistCacheCleanDelay	PLAYLIST_CACHE_CLEAN_DELAY	5 minutes	Time between each cleanup of the cache (to remove expired playlists)
UserAgent	USER_AGENT	Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36	User-Agent header used for requests to SoundCloud
ClientID	CLIENT_ID	(empty)	Authorization token for requests to SoundCloud. It's automatically extracted from the current version of the website, but you can override it if there are issues
DNSCacheTTL	DNS_CACHE_TTL	60 minutes	Time until DNS cache expires
EnableAPI	ENABLE_API	false	Should API be enabled?
Network	NETWORK	tcp4	Network to listen on. Can be tcp4, tcp6 or unix
Addr	ADDR	:4664	Address and port (or socket path) for soundcloak to listen on
UnixSocketPerms	UNIX_SOCKET_PERMS	0775	Permissions for unix socket (Network must be set to unix)
Prefork	PREFORK	false	Run multiple instances of soundcloak locally to be able to handle more requests. Each one will be a separate process, so they will have separate cache.
TrustedProxyCheck	TRUSTED_PROXY_CHECK	true	Use X-Forwarded-* headers if IP is in TrustedProxies list. When disabled, those headers will blindly be used.
TrustedProxies	TRUSTED_PROXIES	[]	List of IPs or IP ranges of trusted proxies
CodegenConfig	CODEGEN_CONFIG	false	Embeds the config into the binary, which helps reduce size if you aren't using certain features and generally optimize the binary better. Keep in mind that you will have to rebuild the image/binary each time you want to change config. (Note: you need to run soundcloakctl config codegen or use docker, as it runs it for you)
EmbedFiles	EMBED_FILES	true	Embed files into the binary. Keep in mind that you will have to rebuild the image/binary each time static files are changed (e.g. custom instance files)

Potential issues

Status code 403/429

Your IP address did too many requests to SoundCloud and got blocked for a bit of time.

script/version/clientid not found

soundcloak failed to extract the ClientID token from SoundCloud. This may happen due to your due to changes made by SoundCloud, or IP getting blocked.

In case your IP is not blocked, please report this issue to me on Codeberg or GitHub or elsewhere

As a temporary fix, you can go to SoundCloud website in your browser, open the Developer Tools, perform some actions (like loading a profile or searching) and check the Network tab. There you will see requests to api-v2.soundcloud.com with client_id parameter. You can use this token with the ClientID setting in soundcloak

Tinkering with the frontend

Click to view

I will mainly talk about the static files here. Maybe about the templates too in the future

Keep in mind that by default soundcloak will embed all static files into the built binary. You will need to rebuild each time you want to change something. Or you can also set EmbedFiles to false

The static files are stored in static/assets folder

Overriding files

1. Create a folder named instance in static folder
2. Create a file with the same name as the one you want to override
3. Put whatever you want there

Basic theming

1. Create instance.css file in the static/instance folder
2. Put your CSS rules there:

/* Some basic CSS to change colors of the frontend. Put your own colors here as this one probably looks horrible (I did not test it) */
:root {
    --accent: #ffffff;
    --primary: #000000;
    --secondary: #00010a;
    --0: #fafafa; /* Used for things, such as border color for buttons, etc */
    --text: green;
}

Refer to static/assets/global.css file for existing rules.

Instance list

To get listed on the instance list, create a discussion with some information about your instance, or reach out privately

Basic rules:

1. Do not collect user information (either yourself, or by including 3rd party tooling which does that)
2. If you are modifying the source code, publish those changes somewhere.

Also, keep in mind that the instance list will periodically hit the /_/info endpoint on your instance (usually each 10 minutes) in order to display the instance settings. If you do not want this to happen, state it in your discussion/message, and I will exclude your instance from this checking.

The source code powering the instance list can be found here