Organizations: allow uploading avatar

.gitignore

@@ -38,6 +38,7 @@ media/json
 media/man
 media/pdf
 media/static
+media/usercontent
 /static
 node_modules
 nodeenv

dockerfiles/nginx/web.conf.template

@@ -18,6 +18,11 @@ server {
         break;
     }
 
+    location /usercontent/ {
+        proxy_pass http://storage:9000/usercontent/;
+        break;
+    }
+
     location / {
         proxy_pass http://web:8000/;
         proxy_set_header X-Forwarded-Host $host;

readthedocs/organizations/forms.py

@@ -7,6 +7,7 @@
 from django.core.validators import EmailValidator
 from django.db.models import Q
 from django.utils.translation import gettext_lazy as _
+from PIL import Image
 
 from readthedocs.core.history import SimpleHistoryModelForm
 from readthedocs.core.permissions import AdminPermission
@@ -36,7 +37,7 @@ class OrganizationForm(SimpleHistoryModelForm):
 
     class Meta:
         model = Organization
-        fields = ["name", "email", "description", "url"]
+        fields = ["name", "email", "avatar", "description", "url"]
         labels = {
             "name": _("Organization Name"),
             "email": _("Billing Email"),
@@ -78,6 +79,22 @@ def clean_name(self):
             )
         return name
 
+    def clean_avatar(self):
+        avatar = self.cleaned_data.get("avatar")
+        if avatar:
+            if avatar.size > 750 * 1024:
+                raise forms.ValidationError(
+                    _("Avatar image size must not exceed 750KB."),
+                )
+            try:
+                img = Image.open(avatar)
+            except Exception:
+                raise ValidationError("Could not process image. Please upload a valid image file.")
+            width, height = img.size
+            if width > 500 or height > 500:
+                raise ValidationError("The image dimensions cannot exceed 500x500 pixels.")
+        return avatar
+
 
 class OrganizationSignupFormBase(OrganizationForm):
     """

readthedocs/organizations/migrations/0016_organization_avatar.py

@@ -0,0 +1,62 @@
+# Generated by Django 5.2.3 on 2025-06-17 22:20
+import django.core.validators
+from django.db import migrations
+from django.db import models
+from django_safemigrate import Safe
+
+import readthedocs.organizations.models
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy()
+
+    dependencies = [
+        ("organizations", "0015_remove_unused_indexes"),
+        ("projects", "0148_remove_unused_indexes"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="historicalorganization",
+            name="avatar",
+            field=models.TextField(
+                blank=True,
+                help_text="Avatar for your organization (JPG or PNG format, max 500x500px, 750KB)",
+                max_length=100,
+                null=True,
+                validators=[
+                    django.core.validators.FileExtensionValidator(
+                        allowed_extensions=["jpg", "jpeg", "png"]
+                    )
+                ],
+                verbose_name="Avatar",
+            ),
+        ),
+        migrations.AddField(
+            model_name="organization",
+            name="avatar",
+            field=models.ImageField(
+                blank=True,
+                help_text="Avatar for your organization (JPG or PNG format, max 500x500px, 750KB)",
+                null=True,
+                storage=readthedocs.organizations.models._get_user_content_storage,
+                upload_to=readthedocs.organizations.models._upload_organization_avatar_to,
+                validators=[
+                    django.core.validators.FileExtensionValidator(
+                        allowed_extensions=["jpg", "jpeg", "png"]
+                    )
+                ],
+                verbose_name="Avatar",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="organization",
+            name="projects",
+            field=models.ManyToManyField(
+                blank=True,
+                related_name="organizations",
+                to="projects.project",
+                verbose_name="Projects",
+            ),
+        ),
+    ]

readthedocs/organizations/models.py

@@ -5,10 +5,13 @@
 from django.contrib.auth.models import User
 from django.contrib.contenttypes.fields import GenericRelation
 from django.contrib.contenttypes.models import ContentType
+from django.core.files.storage import storages
+from django.core.validators import FileExtensionValidator
 from django.db import models
 from django.urls import reverse
 from django.utils.crypto import salted_hmac
 from django.utils.translation import gettext_lazy as _
+from django_gravatar.helpers import get_gravatar_url
 from djstripe.enums import SubscriptionStatus
 
 from readthedocs.core.history import ExtraHistoricalRecords
@@ -26,6 +29,21 @@
 log = structlog.get_logger(__name__)
 
 
+def _upload_organization_avatar_to(instance, filename):
+    extension = filename.split(".")[-1].lower()
+    return f"avatars/organizations/{instance.pk}.{extension}"
+
+
+def _get_user_content_storage():
+    """
+    Get the storage for user content.
+
+    Use a function for storage instead of directly assigning the instance
+    to avoid hardcoding the backend in the migration file.
+    """
+    return storages["usercontent"]
+
+
 class Organization(models.Model):
     """Organization model."""
 
@@ -38,6 +56,7 @@ class Organization(models.Model):
         "projects.Project",
         verbose_name=_("Projects"),
         related_name="organizations",
+        blank=True,
     )
     owners = models.ManyToManyField(
         User,
@@ -129,6 +148,16 @@ class Organization(models.Model):
         object_id_field="attached_to_id",
     )
 
+    avatar = models.ImageField(
+        _("Avatar"),
+        upload_to=_upload_organization_avatar_to,
+        storage=_get_user_content_storage,
+        validators=[FileExtensionValidator(allowed_extensions=["jpg", "jpeg", "png"])],
+        blank=True,
+        null=True,
+        help_text="Avatar for your organization (JPG or PNG format, max 500x500px, 750KB)",
+    )
+
     # Managers
     objects = OrganizationQuerySet.as_manager()
     history = ExtraHistoricalRecords()
@@ -214,6 +243,17 @@ def add_member(self, user, team):
             member = TeamMember.objects.create(team=team, member=user)
         return member
 
+    def get_avatar_url(self):
+        """
+        Get the URL of the organization's avatar.
+
+        Use the `avatar` field if it exists, otherwise use
+        the gravatar from the organization's email.
+        """
+        if self.avatar:
+            return self.avatar.url
+        return get_gravatar_url(self.email, size=100)
+
 
 class OrganizationOwner(models.Model):
     """Intermediate table for Organization <-> User relationships."""

readthedocs/organizations/tests/test_views.py

@@ -1,4 +1,6 @@
 import csv
+from django.core.files.uploadedfile import SimpleUploadedFile
+import io
 import itertools
 from unittest import mock
 
@@ -9,6 +11,7 @@
 from django.urls import reverse
 from django.utils import timezone
 from django_dynamic_fixture import get
+from PIL import Image
 
 from readthedocs.audit.models import AuditLog
 from readthedocs.core.utils import slugify
@@ -59,6 +62,105 @@ def test_update(self):
         # The slug hasn't changed.
         self.assertEqual(self.organization.slug, org_slug)
 
+    def _create_image(self, size=(100, 100), format='PNG'):
+        """Helper to create an in-memory image file."""
+        image = Image.new(mode='RGB', size=size, color=(0, 0, 0))
+        image_bytes = io.BytesIO()
+        image.save(image_bytes, format=format)
+        image_bytes.seek(0)
+        return image_bytes
+
+    def test_update_avatar(self):
+        avatar_file = SimpleUploadedFile(
+            name='test.png',
+            content=self._create_image(size=(100, 100)).read(),
+            content_type='image/png'
+        )
+
+        response = self.client.post(
+            reverse("organization_edit", args=[self.organization.slug]),
+            {
+                "name": "New name",
+                "email": "[email protected]",
+                "description": "Description",
+                "url": "https://readthedocs.org",
+                "avatar": avatar_file,
+            },
+        )
+        assert response.status_code == 302
+        self.organization.refresh_from_db()
+        assert self.organization.avatar
+        assert self.organization.avatar.name == f"avatars/organizations/{self.organization.pk}.png"
+
+    def test_update_avatar_invalid_dimensions(self):
+        avatar_file = SimpleUploadedFile(
+            name='test.png',
+            content=self._create_image(size=(1000, 1000)).read(),
+            content_type='image/png'
+        )
+
+        response = self.client.post(
+            reverse("organization_edit", args=[self.organization.slug]),
+            {
+                "name": "New name",
+                "email": "[email protected]",
+                "description": "Description",
+                "url": "https://readthedocs.org",
+                "avatar": avatar_file,
+            },
+        )
+        assert response.status_code == 200
+        form = response.context_data['form']
+        assert not form.is_valid()
+        assert 'avatar' in form.errors
+        assert "The image dimensions cannot exceed" in form.errors['avatar'][0]
+
+    def test_update_avatar_invalid_image(self):
+        avatar_file = SimpleUploadedFile(
+            name='test.txt',
+            content=b'This is not an image file.',
+            content_type='text/plain'
+        )
+
+        response = self.client.post(
+            reverse("organization_edit", args=[self.organization.slug]),
+            {
+                "name": "New name",
+                "email": "[email protected]",
+                "description": "Description",
+                "url": "https://readthedocs.org",
+                "avatar": avatar_file,
+            },
+        )
+        assert response.status_code == 200
+        form = response.context_data['form']
+        assert not form.is_valid()
+        assert 'avatar' in form.errors
+        assert "Upload a valid image." in form.errors['avatar'][0]
+
+    def test_update_avatar_invalid_extension(self):
+        avatar_file = SimpleUploadedFile(
+            name='test.gif',
+            content=self._create_image(size=(100, 100), format='GIF').read(),
+            content_type='image/gif'
+        )
+
+        response = self.client.post(
+            reverse("organization_edit", args=[self.organization.slug]),
+            {
+                "name": "New name",
+                "email": "[email protected]",
+                "description": "Description",
+                "url": "https://readthedocs.org",
+                "avatar": avatar_file,
+            },
+        )
+        assert response.status_code == 200
+        form = response.context_data['form']
+        assert not form.is_valid()
+        assert 'avatar' in form.errors
+        assert "File extension “gif” is not allowed" in form.errors['avatar'][0]
+
     def test_change_name(self):
         """
         Changing the name of the organization won't change the slug.

readthedocs/settings/base.py

@@ -6,6 +6,7 @@
 import subprocess
 
 import structlog
+from pathlib import Path
 from celery.schedules import crontab
 from corsheaders.defaults import default_headers
 from django.conf.global_settings import PASSWORD_HASHERS
@@ -1037,6 +1038,13 @@ def STORAGES(self):
             "staticfiles": {
                 "BACKEND": self.RTD_STATICFILES_STORAGE,
             },
+            "usercontent": {
+                "BACKEND": "django.core.files.storage.FileSystemStorage",
+                "OPTIONS": {
+                    "location": Path(self.MEDIA_ROOT) / "usercontent",
+                    "allow_overwrite": True,
+                }
+            },
         }
 
     @property

readthedocs/settings/docker_compose.py

@@ -240,5 +240,17 @@ def SOCIALACCOUNT_PROVIDERS(self):
 
     RTD_FILETREEDIFF_ALL = "RTD_FILETREEDIFF_ALL" in os.environ
 
+    @property
+    def STORAGES(self):
+        storages = super().STORAGES
+        storages["usercontent"] = {
+            "BACKEND": "storages.backends.s3.S3Storage",
+            "OPTIONS": {
+                "bucket_name": os.environ.get("RTD_S3_USER_CONTENT_STORAGE_BUCKET", "usercontent"),
+                "url_protocol": "http:",
+                "custom_domain": self.PRODUCTION_DOMAIN + "/usercontent",
+            },
+        }
+        return storages
 
 DockerBaseSettings.load_settings(__name__)

requirements/deploy.txt

@@ -283,6 +283,8 @@ parso==0.8.4
     # via jedi
 pexpect==4.9.0
     # via ipython
+pillow==11.2.1
+    # via -r requirements/pip.txt
 platformdirs==4.3.8
     # via
     #   -r requirements/pip.txt

requirements/docker.txt

@@ -302,6 +302,8 @@ pdbpp==0.11.6
     # via -r requirements/docker.in
 pexpect==4.9.0
     # via ipython
+pillow==11.2.1
+    # via -r requirements/pip.txt
 platformdirs==4.3.8
     # via
     #   -r requirements/pip.txt

requirements/pip.in

@@ -38,6 +38,9 @@ django-safemigrate
 # Impersonate users in the Django admin for support.
 django-impersonate
 
+# For ImageField
+Pillow
+
 requests
 requests-toolbelt
 slumber

requirements/pip.txt

@@ -212,6 +212,8 @@ packaging==25.0
     #   drf-extensions
     #   gunicorn
     #   kombu
+pillow==11.2.1
+    # via -r requirements/pip.in
 platformdirs==4.3.8
     # via virtualenv
 prompt-toolkit==3.0.51